diff --git a/restservice/src/main/java/com/plannaplan/controllers/CommisionController.java b/restservice/src/main/java/com/plannaplan/controllers/CommisionController.java index 3fe4ba2..2ce264a 100755 --- a/restservice/src/main/java/com/plannaplan/controllers/CommisionController.java +++ b/restservice/src/main/java/com/plannaplan/controllers/CommisionController.java @@ -43,6 +43,10 @@ import java.util.HashMap; import com.plannaplan.responses.mappers.AssignmentResponseMappers; import com.plannaplan.responses.models.AssignmentResponse; +/** + * Rest controller to Commision and Assignment related endpoints. More detailed + * api docs is available via swagger + */ @RestController @CrossOrigin @RequestMapping("/api/" + App.API_VERSION + "/commisions") @@ -64,6 +68,11 @@ public class CommisionController extends TokenBasedController { public CommisionController() { } + /** + * @param groups to make assignmetns + * @param userId user to assign to groups + * @return was operations success + */ @PostMapping(value = { "/user", "/user/{id}" }) @ApiOperation(value = "Create commision with assignents to given groups. If group doesn't exist error will be thrown") public ResponseEntity addCommision( @@ -108,6 +117,11 @@ public class CommisionController extends TokenBasedController { } } + /** + * @param groups should include groups list in response + * @return list of user all commisions (history of schedules) + * @throws UserNotFoundException if user was found + */ @GetMapping("/user") @ApiOperation("Return list of user all commisions (history of schedules)") public ResponseEntity> getAlCommisions( @@ -127,6 +141,11 @@ public class CommisionController extends TokenBasedController { return new ResponseEntity<>(result, HttpStatus.OK); } + /** + * @return current schedule of user indenified via token + * @throws Exception if incorrect role was trying to see self schedule (for + * example DEANERY don't have a schedule) + */ @GetMapping("/user/schedule") @ApiOperation(value = "Return user current assignemts (from newest commision). STUDENT Token needs to be provided.") public ResponseEntity> getCurrentAssignments() throws Exception { @@ -144,6 +163,12 @@ public class CommisionController extends TokenBasedController { return new ResponseEntity<>(new ArrayList<>(), HttpStatus.OK); } + /** + * @param userId user id in db + * @param groups should commision include assigned groups list + * @return list of commisions for given user + * @throws UserNotFoundException + */ @PreAuthorize("hasRole('ROLE_DEANERY')") @GetMapping("/user/{id}") @ApiOperation("Return list of commisions for given user. To be able to access this data u need to provide DEANERY token") @@ -163,6 +188,11 @@ public class CommisionController extends TokenBasedController { return new ResponseEntity<>(result, HttpStatus.OK); } + /** + * @param userId schedule to display owner + * @return user's schedule + * @throws Exception if incorrect access atempt occured + */ @PreAuthorize("hasRole('ROLE_DEANERY')") @GetMapping("/user/{id}/schedule") @ApiOperation(value = "Return given user current assignemts (from newest commision). DEANERY Token needs to be provided.") diff --git a/restservice/src/main/java/com/plannaplan/controllers/ConfigController.java b/restservice/src/main/java/com/plannaplan/controllers/ConfigController.java index 9b59955..b4769df 100755 --- a/restservice/src/main/java/com/plannaplan/controllers/ConfigController.java +++ b/restservice/src/main/java/com/plannaplan/controllers/ConfigController.java @@ -35,6 +35,10 @@ import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; +/** + * Rest controller to Config related endpoints. More detailed api docs is + * available via swagger + */ @RestController @CrossOrigin @RequestMapping("/api/" + App.API_VERSION + "/configurator") @@ -47,14 +51,22 @@ public class ConfigController { @Value("${plannaplan.dev}") private boolean isDev; - + @Autowired private ConfiguratorService contrl; @Autowired - private UserService userService; - + private UserService userService; + /** + * @param file file .xlsx that contains courses and groups with + * apoinnted rules + * @param firstTourBegin formated string dd.MM.yyyy + * @param firstTourEnd formated string dd.MM.yyyy + * @param secondTourBegin formated string dd.MM.yyyy + * @param secondTourEnd formated string dd.MM.yyyy + * @return was config success + */ @PostMapping(path = "/config", consumes = { "multipart/form-data" }) @PreAuthorize("hasRole('ROLE_ADMIN')") @ApiOperation("Imports data to system. To call you need to provide ADMIN token") @@ -82,7 +94,13 @@ public class ConfigController { } } - + /** + * @param firstTourBegin formated string dd.MM.yyyy + * @param firstTourEnd formated string dd.MM.yyyy + * @param secondTourBegin formated string dd.MM.yyyy + * @param secondTourEnd formated string dd.MM.yyyy + * @return was operation successful + */ @PostMapping(path = "/config/tours") @PreAuthorize("hasRole('ROLE_ADMIN')") @ApiOperation("Set tours dates. To call you need to provide ADMIN token") @@ -104,12 +122,15 @@ public class ConfigController { return new ResponseEntity<>("Sucess", HttpStatus.OK); } + /** + * @param file file .xlsx that contains courses and groups with + * @return was operation successfull + */ @PostMapping(path = "/config/courses", consumes = { "multipart/form-data" }) @PreAuthorize("hasRole('ROLE_ADMIN')") @ApiOperation("Imports data to system. To call you need to provide ADMIN token") public ResponseEntity configAppChangeCources( - @RequestParam("file") @ApiParam(value = "file .xlsx that contains courses and groups with apoinnted rules") MultipartFile file) - { + @RequestParam("file") @ApiParam(value = "file .xlsx that contains courses and groups with apoinnted rules") MultipartFile file) { try { this.contrl.importCoursesStream(file.getInputStream()); return new ResponseEntity<>("Sucess", HttpStatus.OK); @@ -118,15 +139,20 @@ public class ConfigController { } } + /** + * @param ticket CAS ticket to get user wuthority + * @return was admin created + */ @PostMapping(path = "/admin/init") @ApiOperation("It can be run only in the initialization of the application. It will create admin user to manage the application.") - public ResponseEntity initAdmin(@RequestParam("ticket") @ApiParam(value = "Ticket for validation.") String ticket){ - if (this.userService.adminExists()){ + public ResponseEntity initAdmin( + @RequestParam("ticket") @ApiParam(value = "Ticket for validation.") String ticket) { + if (this.userService.adminExists()) { return new ResponseEntity<>("Admin had been already created.", HttpStatus.FORBIDDEN); } - + final CasValidator validator = isDev ? new DefaultUAMCasValidator(serviceUrl, ticket) - : new CustomUAMCasValidator(serviceUrl, ticket); + : new CustomUAMCasValidator(serviceUrl, ticket); try { final CasUserIdentity casUserIdentity = validator.validate(); @@ -140,5 +166,5 @@ public class ConfigController { } catch (Exception e) { return new ResponseEntity<>("Internal Server Error", HttpStatus.INTERNAL_SERVER_ERROR); } - } + } } \ No newline at end of file diff --git a/restservice/src/main/java/com/plannaplan/controllers/CoursesController.java b/restservice/src/main/java/com/plannaplan/controllers/CoursesController.java index 011c707..e20a9cc 100755 --- a/restservice/src/main/java/com/plannaplan/controllers/CoursesController.java +++ b/restservice/src/main/java/com/plannaplan/controllers/CoursesController.java @@ -29,6 +29,10 @@ import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import com.plannaplan.responses.models.abstracts.CoursesResponse; +/** + * Rest controller to Courses related endpoints. More detailed api docs is + * available via swagger + */ @RestController @CrossOrigin @RequestMapping("/api/" + App.API_VERSION + "/courses") @@ -41,6 +45,11 @@ public class CoursesController { @Autowired private GroupService groupService; + /** + * @param groups should include groups in response + * @param takenPlaces should include groups in response + * @return list of all courses in system + */ @GetMapping("/all") @ApiOperation(value = "Return all courses") public ResponseEntity> getMethodName( diff --git a/restservice/src/main/java/com/plannaplan/controllers/GroupController.java b/restservice/src/main/java/com/plannaplan/controllers/GroupController.java index 0af2431..a11f5e2 100755 --- a/restservice/src/main/java/com/plannaplan/controllers/GroupController.java +++ b/restservice/src/main/java/com/plannaplan/controllers/GroupController.java @@ -27,9 +27,12 @@ import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; +/** + * Rest controller to Groups related endpoints. More detailed api docs is + * available via swagger + */ @RestController @CrossOrigin - @RequestMapping("/api/" + App.API_VERSION + "/groups") @Api(tags = { "Group" }, value = "Group", description = "Enpoints to deal with gorups. Group is related directly to course and can be either class and lecture") @@ -37,6 +40,12 @@ public class GroupController { @Autowired private GroupService groupService; + /** + * @param id course to display with groups + * @param capacity should include capaticty in response + * @param takenPlaces should include takenPlaces in response + * @return CourseWithGroupsResponse + */ @GetMapping("/course/{id}") @ApiOperation(value = "Return list of lectures and classes (if present) given course") public ResponseEntity> getCourses( @@ -61,6 +70,11 @@ public class GroupController { return new ResponseEntity<>(GroupsMappers.mapToGetCourseGroupsDefaultResponse(groups), HttpStatus.OK); } + /** + * @param id group id to change capacity + * @param newcapacity new capacity to insert + * @return ResponseEntity was action success + */ @PutMapping("/{id}/capacity") @PreAuthorize("hasRole('ROLE_DEANERY')") @ApiOperation(value = "Change capacity of given group. You need to provide DEANERY token to be ale to change capacity") diff --git a/restservice/src/main/java/com/plannaplan/controllers/TokenBasedController.java b/restservice/src/main/java/com/plannaplan/controllers/TokenBasedController.java index 504ce33..b815f52 100755 --- a/restservice/src/main/java/com/plannaplan/controllers/TokenBasedController.java +++ b/restservice/src/main/java/com/plannaplan/controllers/TokenBasedController.java @@ -11,6 +11,10 @@ import org.springframework.security.core.Authentication; import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.security.authentication.AnonymousAuthenticationToken; +/** + * Abstract class for controllers that requires token to extra authorize action + * beyond spring security + */ public abstract class TokenBasedController { @Autowired protected UserService userService; @@ -18,6 +22,10 @@ public abstract class TokenBasedController { public TokenBasedController() { } + /** + * @return get currect user based no current spring context + * @throws UserNotFoundException if user was not fount + */ protected Optional getCurrentUser() throws UserNotFoundException { Authentication authentication = SecurityContextHolder.getContext().getAuthentication(); diff --git a/restservice/src/main/java/com/plannaplan/controllers/TokenController.java b/restservice/src/main/java/com/plannaplan/controllers/TokenController.java index 18b66c8..0b5e219 100755 --- a/restservice/src/main/java/com/plannaplan/controllers/TokenController.java +++ b/restservice/src/main/java/com/plannaplan/controllers/TokenController.java @@ -26,6 +26,10 @@ import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; +/** + * Rest controller to Token related endpoints. More detailed api docs is + * available via swagger + */ @RestController @CrossOrigin @Api(tags = { "Token" }, value = "Token", description = "Enpoints to get authorization.") @@ -40,6 +44,10 @@ public class TokenController { @Autowired private UserService userService; + /** + * @param ticket via CAS obtained ticket - it's base to auth user + * @return TokenResponse if operation was success + */ @GetMapping("/token") @ApiOperation(value = "Endpoint to access token required to call secured endpoints. In order to access token we need to provide access token comming from unviersity CAS system") public ResponseEntity getToken( @@ -64,6 +72,11 @@ public class TokenController { } } + /** + * @param refreshToken refresh token obtained via /token endpoint + * @return TokenResponse if operation was success + * @throws NullPointerException is thrown if user was not found by refrshtoken + */ @GetMapping("/token/refresh") @ApiOperation(value = "Endpoint to access new token based on refresh token. It's needed when request with provided token fail with code 403") public ResponseEntity getRefreshToken( diff --git a/restservice/src/main/java/com/plannaplan/controllers/UsersController.java b/restservice/src/main/java/com/plannaplan/controllers/UsersController.java index 7d3614a..ddc8bfd 100755 --- a/restservice/src/main/java/com/plannaplan/controllers/UsersController.java +++ b/restservice/src/main/java/com/plannaplan/controllers/UsersController.java @@ -27,6 +27,10 @@ import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; +/** + * Rest controller to assignments related endpoints. More detailed api docs is + * available via swagger + */ @RestController @CrossOrigin @RequestMapping("/api/" + App.API_VERSION + "/users") @@ -36,6 +40,10 @@ public class UsersController { @Autowired private UserService userService; + /** + * @param query to filrer userst with STUDENT role + * @return list found + */ @GetMapping("/student/search") @PreAuthorize("hasRole('ROLE_DEANERY')") @ApiOperation(value = "Serch for user by providing query. If query is empty it will return all students. You need token with DEANERY role to call this") @@ -46,6 +54,9 @@ public class UsersController { return new ResponseEntity<>(response, HttpStatus.OK); } + /** + * @return list of all studnents + */ @GetMapping("/students") @PreAuthorize("hasRole('ROLE_DEANERY')") @ApiOperation(value = "Gets all students. You need token with DEANERY role to call this") @@ -55,10 +66,16 @@ public class UsersController { return new ResponseEntity<>(response, HttpStatus.OK); } + /** + * @param authority USOS ID or E-mail. If user does not exist it should be USOS + * ID + * @return response entity was operation with succcesss + */ @PostMapping(path = "/admin") @PreAuthorize("hasRole('ROLE_ADMIN')") @ApiOperation(value = "Adds new admin user.") - public ResponseEntity addAdmin(@RequestParam("authority") @ApiParam(value = "USOS ID or E-mail. If user does not exist it should be USOS ID") String authority) { + public ResponseEntity addAdmin( + @RequestParam("authority") @ApiParam(value = "USOS ID or E-mail. If user does not exist it should be USOS ID") String authority) { final Optional userResponse = this.userService.getByAuthority(authority); final User user = userResponse.orElseGet(() -> new User(null, null, null, authority, UserRoles.ADMIN)); user.setRole(UserRoles.ADMIN); @@ -66,10 +83,16 @@ public class UsersController { return new ResponseEntity<>("Success", HttpStatus.OK); } + /** + * @param authority USOS ID or E-mail. If user does not exist it should be USOS + * ID + * @return response entity was operation with succcesss + */ @PostMapping(path = "/deanery") @PreAuthorize("hasRole('ROLE_ADMIN')") @ApiOperation(value = "Adds new deanery user.") - public ResponseEntity addDeanery(@RequestParam("authority") @ApiParam(value = "USOS ID or E-mail. If user does not exist it should be USOS ID") String authority) { + public ResponseEntity addDeanery( + @RequestParam("authority") @ApiParam(value = "USOS ID or E-mail. If user does not exist it should be USOS ID") String authority) { final Optional userResponse = this.userService.getByAuthority(authority); final User user = userResponse.orElseGet(() -> new User(null, null, null, authority, UserRoles.DEANERY)); user.setRole(UserRoles.DEANERY);