From e7ca60150899959ee4db489c1daef3f69a7e2630 Mon Sep 17 00:00:00 2001 From: Moritzjenny <moritzjenny@hotmail.com> Date: Tue, 8 Oct 2019 13:44:32 +0200 Subject: [PATCH] OO-4297 add additional annotations for @queryParameter --- .../restapi/CertificationWebService.java | 6 ++-- .../course/db/restapi/CourseDbWebService.java | 3 +- .../olat/course/nodes/co/COWebService.java | 15 +++++---- .../restapi/CurriculumElementsWebService.java | 24 +++++++++++++- .../fo/restapi/ForumCourseNodeWebService.java | 21 ++++++------ .../modules/fo/restapi/ForumWebService.java | 33 +++++++++++++++---- .../restapi/RegistrationWebService.java | 12 ++++++- .../group/LearningGroupWebService.java | 3 +- .../olat/restapi/group/MyGroupWebService.java | 11 ++++--- 9 files changed, 94 insertions(+), 34 deletions(-) diff --git a/src/main/java/org/olat/course/certificate/restapi/CertificationWebService.java b/src/main/java/org/olat/course/certificate/restapi/CertificationWebService.java index 985cc063ec8..fff4b369613 100644 --- a/src/main/java/org/olat/course/certificate/restapi/CertificationWebService.java +++ b/src/main/java/org/olat/course/certificate/restapi/CertificationWebService.java @@ -64,6 +64,8 @@ import org.olat.restapi.support.ObjectFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; + +import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; /** @@ -203,8 +205,8 @@ public class CertificationWebService { @PUT @Path("{identityKey}") public Response putCertificate(@PathParam("identityKey") Long identityKey, @PathParam("resourceKey") Long resourceKey, - @QueryParam("score") Float score, @QueryParam("passed") Boolean passed, - @QueryParam("creationDate") String creationDate, + @QueryParam("score")@Parameter(description = "The score which appears in the certificate") Float score, @QueryParam("passed") @Parameter(description = "The passed/failed which appears in the certificate (true/false)") Boolean passed, + @QueryParam("creationDate") @Parameter(description = "The date of the certification") String creationDate, @Context HttpServletRequest request) { Identity assessedIdentity = securityManager.loadIdentityByKey(identityKey); if(assessedIdentity == null) { diff --git a/src/main/java/org/olat/course/db/restapi/CourseDbWebService.java b/src/main/java/org/olat/course/db/restapi/CourseDbWebService.java index 3ad4ae0287f..a340ffae78d 100644 --- a/src/main/java/org/olat/course/db/restapi/CourseDbWebService.java +++ b/src/main/java/org/olat/course/db/restapi/CourseDbWebService.java @@ -54,6 +54,7 @@ import org.olat.restapi.support.vo.KeyValuePair; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; +import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; /** @@ -229,7 +230,7 @@ public class CourseDbWebService { @PUT @Path("values/{name}") public Response putValue(@PathParam("courseId") Long courseId, @PathParam("category") String category, @PathParam("name") String name, - @QueryParam("value") String value, @Context HttpServletRequest request) { + @QueryParam("value") @Parameter(description = "The value of the key value pair") String value, @Context HttpServletRequest request) { return internPutValue(courseId, category, name, value, request); } diff --git a/src/main/java/org/olat/course/nodes/co/COWebService.java b/src/main/java/org/olat/course/nodes/co/COWebService.java index 75a3099195b..632b8fc3f9b 100755 --- a/src/main/java/org/olat/course/nodes/co/COWebService.java +++ b/src/main/java/org/olat/course/nodes/co/COWebService.java @@ -66,6 +66,7 @@ import org.olat.restapi.repository.course.AbstractCourseNodeWebService; import org.springframework.stereotype.Component; import io.swagger.v3.oas.annotations.tags.Tag; +import io.swagger.v3.oas.annotations.Parameter; /** * @@ -114,13 +115,13 @@ public class COWebService extends AbstractCourseNodeWebService { @PUT @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response attachContact(@PathParam("courseId") Long courseId, @QueryParam("parentNodeId") String parentNodeId, - @QueryParam("position") Integer position, @QueryParam("shortTitle") @DefaultValue("undefined") String shortTitle, - @QueryParam("longTitle") @DefaultValue("undefined") String longTitle, @QueryParam("objectives") @DefaultValue("undefined") String objectives, - @QueryParam("visibilityExpertRules") String visibilityExpertRules, @QueryParam("accessExpertRules") String accessExpertRules, - @QueryParam("coaches") @DefaultValue("false") boolean coaches, @QueryParam("participants") @DefaultValue("false") boolean participants, - @QueryParam("groups") String groups, @QueryParam("areas") String areas, @QueryParam("to") String to, - @QueryParam("defaultSubject") String defaultSubject, @QueryParam("defaultBody") String defaultBody, + public Response attachContact(@PathParam("courseId") Long courseId, @QueryParam("parentNodeId") @Parameter(description = "The node's id which will be the parent of this structure")String parentNodeId, + @QueryParam("position") @Parameter(description = "The node's position relative to its sibling nodes (optional)") Integer position, @QueryParam("shortTitle") @Parameter(description = "The node short title") @DefaultValue("undefined") String shortTitle, + @QueryParam("longTitle") @Parameter(description = "The node long title") @DefaultValue("undefined") String longTitle, @QueryParam("objectives") @Parameter(description = "The node learning objectives") @DefaultValue("undefined") String objectives, + @QueryParam("visibilityExpertRules") @Parameter(description = "The rules to view the node (optional)") String visibilityExpertRules, @QueryParam("accessExpertRules") @Parameter(description = "The rules to access the node (optional)") String accessExpertRules, + @QueryParam("coaches") @Parameter(description = "Send to coaches (true/false)") @DefaultValue("false") boolean coaches, @QueryParam("participants") @Parameter(description = "Send to participants (true/false)") @DefaultValue("false") boolean participants, + @QueryParam("groups") @Parameter(description = "A list of learning groups (list of keys)") String groups, @QueryParam("areas") @Parameter(description = "A list of learning areas (list of keys)") String areas, @QueryParam("to") String to, + @QueryParam("defaultSubject") @Parameter(description = "The default subject") String defaultSubject, @QueryParam("defaultBody") @Parameter(description = "The default body text") String defaultBody, @Context HttpServletRequest request) { ContactConfigDelegate config = new ContactConfigDelegate(coaches, participants, groups, areas, to, defaultSubject, defaultBody); diff --git a/src/main/java/org/olat/modules/curriculum/restapi/CurriculumElementsWebService.java b/src/main/java/org/olat/modules/curriculum/restapi/CurriculumElementsWebService.java index 4571f39b655..bf1047d1553 100644 --- a/src/main/java/org/olat/modules/curriculum/restapi/CurriculumElementsWebService.java +++ b/src/main/java/org/olat/modules/curriculum/restapi/CurriculumElementsWebService.java @@ -68,6 +68,15 @@ import org.olat.user.restapi.UserVO; import org.olat.user.restapi.UserVOFactory; import org.springframework.beans.factory.annotation.Autowired; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + /** * The security checks are done by the CurriculumsWebService. * @@ -543,7 +552,20 @@ public class CurriculumElementsWebService { */ @GET @Path("{curriculumElementKey}/users") - public Response getUsers(@PathParam("curriculumElementKey") Long curriculumElementKey, @QueryParam("role") String role) { + @Operation(summary = "Get all members", + description = "Get all members of the specified curriculum element. A query parameter can\n" + + " specify the role of them") + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "The array of authors", + content = { + @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))), + @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) + } + ), + @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"), + @ApiResponse(responseCode = "401", description = "The course not found")} + ) + public Response getUsers(@PathParam("curriculumElementKey") Long curriculumElementKey, @QueryParam("role") @Parameter(description = "Filter by specific role") String role) { CurriculumElement curriculumElement = curriculumService.getCurriculumElement(new CurriculumElementRefImpl(curriculumElementKey)); if(curriculumElement == null) { return Response.serverError().status(Status.NOT_FOUND).build(); diff --git a/src/main/java/org/olat/modules/fo/restapi/ForumCourseNodeWebService.java b/src/main/java/org/olat/modules/fo/restapi/ForumCourseNodeWebService.java index bf00414e0ce..c6e4d74b7ba 100644 --- a/src/main/java/org/olat/modules/fo/restapi/ForumCourseNodeWebService.java +++ b/src/main/java/org/olat/modules/fo/restapi/ForumCourseNodeWebService.java @@ -76,6 +76,7 @@ import org.olat.restapi.security.RestSecurityHelper; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; +import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; /** @@ -207,12 +208,12 @@ public class ForumCourseNodeWebService extends AbstractCourseNodeWebService { */ @PUT @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response attachForum(@PathParam("courseId") Long courseId, @QueryParam("parentNodeId") String parentNodeId, - @QueryParam("position") Integer position, @QueryParam("shortTitle") @DefaultValue("undefined") String shortTitle, - @QueryParam("longTitle") @DefaultValue("undefined") String longTitle, @QueryParam("objectives") @DefaultValue("undefined") String objectives, - @QueryParam("visibilityExpertRules") String visibilityExpertRules, @QueryParam("accessExpertRules") String accessExpertRules, - @QueryParam("moderatorExpertRules") String moderatorExpertRules, @QueryParam("posterExpertRules") String posterExpertRules, - @QueryParam("readerExpertRules") String readerExpertRules, @Context HttpServletRequest request) { + public Response attachForum(@PathParam("courseId") Long courseId, @QueryParam("parentNodeId") @Parameter(description = "The node's id which will be the parent of this single page") String parentNodeId, + @QueryParam("position") @Parameter(description = "The node's position relative to its sibling nodes (optional)") Integer position, @QueryParam("shortTitle") @Parameter(description = "The node short title") @DefaultValue("undefined") String shortTitle, + @QueryParam("longTitle") @Parameter(description = "The node long title") @DefaultValue("undefined") String longTitle, @QueryParam("objectives") @Parameter(description = "The node learning objectives") @DefaultValue("undefined") String objectives, + @QueryParam("visibilityExpertRules") @Parameter(description = "The rules to view the node (optional)") String visibilityExpertRules, @QueryParam("accessExpertRules") @Parameter(description = "The rules to access the node (optional)") String accessExpertRules, + @QueryParam("moderatorExpertRules") @Parameter(description = "The rules to moderate the node (optional)") String moderatorExpertRules, @QueryParam("posterExpertRules") @Parameter(description = "The rules to post the node (optional)") String posterExpertRules, + @QueryParam("readerExpertRules") @Parameter(description = "The rules to read the node (optional)") String readerExpertRules, @Context HttpServletRequest request) { ForumCustomConfig config = new ForumCustomConfig(moderatorExpertRules, posterExpertRules, readerExpertRules); return attach(courseId, parentNodeId, "fo", position, shortTitle, longTitle, objectives, visibilityExpertRules, accessExpertRules, config, request); } @@ -316,8 +317,8 @@ public class ForumCourseNodeWebService extends AbstractCourseNodeWebService { @PUT @Path("{nodeId}/thread") @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response newThreadToForum(@PathParam("courseId") Long courseId, @PathParam("nodeId") String nodeId, @QueryParam("title") String title, - @QueryParam("body") String body, @QueryParam("identityName") String identityName, @QueryParam("sticky") Boolean isSticky, + public Response newThreadToForum(@PathParam("courseId") Long courseId, @PathParam("nodeId") String nodeId, @QueryParam("title")@Parameter(description = "The title for the first post in the thread") String title, + @QueryParam("body") @Parameter(description = "The body for the first post in the thread") String body, @QueryParam("identityName") @Parameter(description = "The author identity name (optional)")String identityName, @QueryParam("sticky")@Parameter(description = "Creates sticky thread.") Boolean isSticky, @Context HttpServletRequest request) { return addMessage(courseId, nodeId, null, title, body, identityName, isSticky, request); @@ -345,8 +346,8 @@ public class ForumCourseNodeWebService extends AbstractCourseNodeWebService { @PUT @Path("{nodeId}/message") @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response newMessageToForum(@PathParam("courseId") Long courseId, @PathParam("nodeId") String nodeId, @QueryParam("parentMessageId") Long parentMessageId, @QueryParam("title") String title, - @QueryParam("body") String body, @QueryParam("identityName") String identityName, @Context HttpServletRequest request) { + public Response newMessageToForum(@PathParam("courseId") Long courseId, @PathParam("nodeId") String nodeId, @QueryParam("parentMessageId") @Parameter(description = "The id of the parent message") Long parentMessageId, @QueryParam("title") @Parameter(description = "The title for the first post in the thread") String title, + @QueryParam("body") @Parameter(description = "The body for the first post in the thread") String body, @QueryParam("identityName") @Parameter(description = "The author identity name (optional)") String identityName, @Context HttpServletRequest request) { if(parentMessageId == null || parentMessageId == 0L) { return Response.serverError().status(Status.NOT_FOUND).build(); diff --git a/src/main/java/org/olat/modules/fo/restapi/ForumWebService.java b/src/main/java/org/olat/modules/fo/restapi/ForumWebService.java index 2b7a8dd611c..5f725e35be2 100644 --- a/src/main/java/org/olat/modules/fo/restapi/ForumWebService.java +++ b/src/main/java/org/olat/modules/fo/restapi/ForumWebService.java @@ -86,6 +86,12 @@ import org.olat.restapi.support.vo.FileVO; import org.springframework.beans.factory.annotation.Autowired; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; import io.swagger.v3.oas.annotations.tags.Tag; /** @@ -233,8 +239,11 @@ public class ForumWebService { @Operation(summary = "Put threads", description = "Creates a new thread in the forum of the course node.") @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response newThreadToForum(@QueryParam("title") String title, - @QueryParam("body") String body, @QueryParam("authorKey") Long authorKey, + + @Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) + public Response newThreadToForum(@QueryParam("title") @Parameter(description = "The title for the first post in the thread") String title, + @QueryParam("body") String body, @QueryParam("authorKey") @Parameter(description = "The author user key (optional)") Long authorKey, + @Context HttpServletRequest httpRequest) { Identity author = getMessageAuthor(authorKey, httpRequest); @@ -271,9 +280,19 @@ public class ForumWebService { @Path("posts/{threadKey}") @Operation(summary = "Get posts", description = "Retrieves the messages in the thread.") - public Response getMessages( @PathParam("threadKey") Long threadKey, @QueryParam("start") @DefaultValue("0") Integer start, - @QueryParam("limit") @DefaultValue("25") Integer limit, @QueryParam("orderBy") @DefaultValue("creationDate") String orderBy, - @QueryParam("asc") @DefaultValue("true") Boolean asc, @Context HttpServletRequest httpRequest, @Context UriInfo uriInfo, + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "Ok.", + content = { + @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = MessageVO.class))), + @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = MessageVO.class))) + } + ), + @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient."), + @ApiResponse(responseCode = "404", description = "The author, forum or message not found.")} + ) + public Response getMessages( @PathParam("threadKey") Long threadKey, @QueryParam("start") @Parameter(description = "Set the date for the earliest thread") @DefaultValue("0") Integer start, + @QueryParam("limit")@Parameter(description = "Limit the amount of threads to be returned.") @DefaultValue("25") Integer limit, @QueryParam("orderBy")@Parameter(description = "orderBy (value name,creationDate)") @DefaultValue("creationDate") String orderBy, + @QueryParam("asc") @Parameter(description = "Determine the type of order.") @DefaultValue("true") Boolean asc, @Context HttpServletRequest httpRequest, @Context UriInfo uriInfo, @Context Request request) { if(forum == null) { @@ -347,8 +366,8 @@ public class ForumWebService { description = "Creates a new reply in the forum of the course node.") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response replyToPost(@PathParam("messageKey") Long messageKey, @QueryParam("title") String title, - @QueryParam("body") String body, @QueryParam("authorKey") Long authorKey, + public Response replyToPost(@PathParam("messageKey") Long messageKey, @QueryParam("title") @Parameter(description = "The title for the first post in the thread") String title, + @QueryParam("body") @Parameter(description = "The body for the first post in the thread") String body, @QueryParam("authorKey") @Parameter(description = "The author user key (optional)") Long authorKey, @Context HttpServletRequest httpRequest, @Context UriInfo uriInfo) { ServletUtil.printOutRequestHeaders(httpRequest); return replyToPost(messageKey, new ReplyVO(title, body), authorKey, httpRequest, uriInfo); diff --git a/src/main/java/org/olat/registration/restapi/RegistrationWebService.java b/src/main/java/org/olat/registration/restapi/RegistrationWebService.java index 44d418d6c3f..7942608fbc6 100644 --- a/src/main/java/org/olat/registration/restapi/RegistrationWebService.java +++ b/src/main/java/org/olat/registration/restapi/RegistrationWebService.java @@ -58,6 +58,12 @@ import org.olat.user.UserModule; import org.springframework.stereotype.Component; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + + /** * * Description:<br> @@ -99,7 +105,11 @@ public class RegistrationWebService { * @return */ @PUT - public Response register(@QueryParam("email") String email, @Context HttpServletRequest request) { + @Operation(summary = "Register with the specified email", description = "Register with the specified email") + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "Registration successful"), + @ApiResponse(responseCode = "304", description = "Already registered, HTTP-Header location set to redirect") }) + public Response register(@QueryParam("email") @Parameter(description = "The email address") String email, @Context HttpServletRequest request) { if (!CoreSpringFactory.getImpl(RegistrationModule.class).isSelfRegistrationEnabled()) { return Response.serverError().status(Status.NOT_FOUND).build(); } diff --git a/src/main/java/org/olat/restapi/group/LearningGroupWebService.java b/src/main/java/org/olat/restapi/group/LearningGroupWebService.java index 2c54ab08fe8..e84827157b6 100644 --- a/src/main/java/org/olat/restapi/group/LearningGroupWebService.java +++ b/src/main/java/org/olat/restapi/group/LearningGroupWebService.java @@ -85,6 +85,7 @@ import org.olat.user.restapi.UserVO; import org.olat.user.restapi.UserVOFactory; import org.springframework.stereotype.Component; +import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; @@ -138,7 +139,7 @@ public class LearningGroupWebService { */ @GET @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response getGroupList(@QueryParam("externalId") String externalId, @QueryParam("managed") Boolean managed, + public Response getGroupList(@QueryParam("externalId") @Parameter(description = "Search with an external ID") String externalId, @QueryParam("managed") @Parameter(description = "(true / false) Search only managed / not managed groups") Boolean managed, @Context HttpServletRequest request) { BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class); List<BusinessGroup> groups; diff --git a/src/main/java/org/olat/restapi/group/MyGroupWebService.java b/src/main/java/org/olat/restapi/group/MyGroupWebService.java index a283b4a0218..ad86117c3d3 100644 --- a/src/main/java/org/olat/restapi/group/MyGroupWebService.java +++ b/src/main/java/org/olat/restapi/group/MyGroupWebService.java @@ -52,6 +52,9 @@ import org.olat.restapi.support.vo.GroupVO; import org.olat.restapi.support.vo.GroupVOes; import org.springframework.beans.factory.annotation.Autowired; +import io.swagger.v3.oas.annotations.Parameter; + + /** * * Description:<br> @@ -91,8 +94,8 @@ public class MyGroupWebService { */ @GET @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response getUserGroupList(@QueryParam("start") @DefaultValue("0") Integer start, @QueryParam("limit") @DefaultValue("25") Integer limit, - @QueryParam("externalId") String externalId, @QueryParam("managed") Boolean managed, + public Response getUserGroupList(@QueryParam("start") @Parameter(description = "The first result") @DefaultValue("0") Integer start, @QueryParam("limit") @Parameter(description = "The maximum results") @DefaultValue("25") Integer limit, + @QueryParam("externalId") @Parameter(description = "Search with an external ID") String externalId, @QueryParam("managed") @Parameter(description = "(true / false) Search only managed / not managed groups") Boolean managed, @Context HttpServletRequest httpRequest, @Context Request request) { return getGroupList(start, limit, externalId, managed, true, true, httpRequest, request); @@ -116,8 +119,8 @@ public class MyGroupWebService { @GET @Path("owner") @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) - public Response getOwnedGroupList(@QueryParam("start") @DefaultValue("0") Integer start, @QueryParam("limit") @DefaultValue("25") Integer limit, - @QueryParam("externalId") String externalId, @QueryParam("managed") Boolean managed, + public Response getOwnedGroupList(@QueryParam("start") @Parameter(description = "The first result") @DefaultValue("0") Integer start, @QueryParam("limit") @Parameter(description = "The maximum results") @DefaultValue("25") Integer limit, + @QueryParam("externalId") @Parameter(description = "Search with an external ID") String externalId, @QueryParam("managed") @Parameter(description = "(true / false) Search only managed / not managed groups") Boolean managed, @Context HttpServletRequest httpRequest, @Context Request request) { return getGroupList(start, limit, externalId, managed, true, false, httpRequest, request); } -- GitLab