This is an automated email from the ASF dual-hosted git repository. sebawagner pushed a commit to branch feature/OPENMEETINGS-2660-update-swagger-rest-api-docs-additional-Web-Services in repository https://gitbox.apache.org/repos/asf/openmeetings.git
commit 55fcb949ae2dd1d482b89835c662a60f946244b8 Author: Sebastian Wagner <[email protected]> AuthorDate: Sat Sep 4 13:06:36 2021 +1200 OPENMEETINGS-2660 Update response codes and objects to be generated. Add UserService API tags for documentation. --- openmeetings-webservice/pom.xml | 4 + .../openmeetings/webservice/RoomWebService.java | 42 +++++++---- .../openmeetings/webservice/UserWebService.java | 86 ++++++++++++++++++---- 3 files changed, 104 insertions(+), 28 deletions(-) diff --git a/openmeetings-webservice/pom.xml b/openmeetings-webservice/pom.xml index 68258c6..0c41b43 100644 --- a/openmeetings-webservice/pom.xml +++ b/openmeetings-webservice/pom.xml @@ -83,6 +83,10 @@ </info> <servers> <server> + <description>Your local OpenMeetings Server</description> + <url>http://localhost:5080/openmeetings/services</url> + </server> + <server> <description>Om Demo Server</description> <url>https://om.alteametasoft.com/openmeetings/services</url> </server> diff --git a/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/RoomWebService.java b/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/RoomWebService.java index 47cbce1..cd629d8 100644 --- a/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/RoomWebService.java +++ b/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/RoomWebService.java @@ -65,6 +65,9 @@ import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; 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.tags.Tag; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.responses.ApiResponse; @@ -119,7 +122,8 @@ public class RoomWebService extends BaseWebService { + " about that ROOM. The List of current-users in the room is Null if you get\n" + " them via SOAP. The Roomtype can be 'conference', 'presentation' or 'interview'.", responses = { - @ApiResponse(responseCode = "200", description = "list of public rooms") + @ApiResponse(responseCode = "200", description = "list of public rooms", content = @Content(array = @ArraySchema(schema = @Schema(implementation = RoomDTO.class)))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public List<RoomDTO> getPublic( @@ -145,7 +149,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "Returns a conference room object", responses = { - @ApiResponse(responseCode = "200", description = "room with the id given") + @ApiResponse(responseCode = "200", description = "room with the id given", content = @Content(schema = @Schema(implementation = RoomDTO.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public RoomDTO getRoomById( @@ -203,7 +208,8 @@ public class RoomWebService extends BaseWebService { + " if yes it returns the room id if not, it will create the room and then\n" + " return the room id of the newly created room", responses = { - @ApiResponse(responseCode = "200", description = "id of the room or error code") + @ApiResponse(responseCode = "200", description = "id of the room or error code", content = @Content(schema = @Schema(implementation = RoomDTO.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public RoomDTO getExternal( @@ -249,7 +255,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "Adds a new ROOM like through the Frontend", responses = { - @ApiResponse(responseCode = "200", description = "Room object or throw error") + @ApiResponse(responseCode = "200", description = "Room object or throw error", content = @Content(schema = @Schema(implementation = RoomDTO.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public RoomDTO add( @@ -279,7 +286,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "Delete a room by its room id", responses = { - @ApiResponse(responseCode = "200", description = "id of the room deleted") + @ApiResponse(responseCode = "200", description = "id of the room deleted", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult delete( @@ -321,7 +329,8 @@ public class RoomWebService extends BaseWebService { + " inside the room and all users that try to enter it will be redirected to\n" + " the redirectURL that is defined in the ROOM-Object.", responses = { - @ApiResponse(responseCode = "200", description = "1 in case of success, -2 otherwise") + @ApiResponse(responseCode = "200", description = "1 in case of success, -2 otherwise", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult close( @@ -365,7 +374,8 @@ public class RoomWebService extends BaseWebService { + " inside the room and all users that try to enter it will be redirected to\n" + " the redirectURL that is defined in the ROOM-Object.", responses = { - @ApiResponse(responseCode = "200", description = "1 in case of success, -2 otherwise") + @ApiResponse(responseCode = "200", description = "1 in case of success, -2 otherwise", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult open( @@ -399,7 +409,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "Kick all uses of a certain room", responses = { - @ApiResponse(responseCode = "200", description = "true if USER was kicked, false otherwise") + @ApiResponse(responseCode = "200", description = "true if USER was kicked, false otherwise", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult kickAll( @@ -434,7 +445,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "kick external USER from given room", responses = { - @ApiResponse(responseCode = "200", description = "'Kicked' if USER was 'Not kicked' otherwise") + @ApiResponse(responseCode = "200", description = "'Kicked' if USER was 'Not kicked' otherwise", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult kick( @@ -463,7 +475,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "Returns the count of users currently in the ROOM with given id", responses = { - @ApiResponse(responseCode = "200", description = "number of users as int") + @ApiResponse(responseCode = "200", description = "number of users as int", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult count( @@ -488,7 +501,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "Returns list of users currently in the ROOM with given id", responses = { - @ApiResponse(responseCode = "200", description = "List of users in the room") + @ApiResponse(responseCode = "200", description = "List of users in the room", content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDTO.class)))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public List<UserDTO> users( @@ -518,7 +532,8 @@ public class RoomWebService extends BaseWebService { @Operation( description = "Method to get invitation hash with given parameters", responses = { - @ApiResponse(responseCode = "200", description = "serviceResult object with the result") + @ApiResponse(responseCode = "200", description = "serviceResult object with the result", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult hash( @@ -565,7 +580,8 @@ public class RoomWebService extends BaseWebService { deprecated = true, description = "Method to clean room white board (all objects will be purged) - Deprecated use WbService#resetWb method instead", responses = { - @ApiResponse(responseCode = "200", description = "serviceResult object with the result") + @ApiResponse(responseCode = "200", description = "serviceResult object with the result", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") } ) public ServiceResult cleanWb(@WebParam(name="sid") @QueryParam("sid") String sid diff --git a/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/UserWebService.java b/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/UserWebService.java index ad7e1b0..63cc196 100644 --- a/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/UserWebService.java +++ b/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/UserWebService.java @@ -26,6 +26,12 @@ import static org.apache.openmeetings.webservice.Constants.TNS; import static org.apache.openmeetings.webservice.Constants.USER_SERVICE_NAME; import static org.apache.openmeetings.webservice.Constants.USER_SERVICE_PORT_NAME; +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.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.tags.Tag; import java.security.NoSuchAlgorithmException; @@ -110,7 +116,16 @@ public class UserWebService extends BaseWebService { @WebMethod @GET @Path("/login") - public ServiceResult login(@WebParam(name="user") @QueryParam("user") String user, @WebParam(name="pass") @QueryParam("pass") String pass) { + @Operation( + description = "Login and create sessionId required for sub-sequent calls", + responses = { + @ApiResponse(responseCode = "200", description = "ServiceResult with error code or SID and userId", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error of server error") + } + ) + public ServiceResult login( + @Parameter(required = true, description = "login or email of Openmeetings user with admin or SOAP-rights") @WebParam(name="user") @QueryParam("user") String user + , @Parameter(required = true, description = "password") @WebParam(name="pass") @QueryParam("pass") String pass) { try { log.debug("Login user"); User u = userDao.login(user, pass); @@ -141,7 +156,16 @@ public class UserWebService extends BaseWebService { @WebMethod @GET @Path("/") - public List<UserDTO> get(@WebParam(name="sid") @QueryParam("sid") String sid) throws ServiceException { + @Operation( + description = "Lists all users in the system!", + responses = { + @ApiResponse(responseCode = "200", description = "list of users", content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDTO.class)))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") + } + ) + public List<UserDTO> get( + @Parameter(required = true, description = "The SID of the User. This SID must be marked as Loggedin") @WebParam(name="sid") @QueryParam("sid") String sid + ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> UserDTO.list(userDao.getAllUsers())); } @@ -162,10 +186,18 @@ public class UserWebService extends BaseWebService { @WebMethod @POST @Path("/") + @Operation( + description = "Adds a new User like through the Frontend, but also does activates the\n" + + " Account To do SSO see the methods to create a hash and use those ones!", + responses = { + @ApiResponse(responseCode = "200", description = "list of users", content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDTO.class)))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") + } + ) public UserDTO add( - @WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="user") @FormParam("user") UserDTO user - , @WebParam(name="confirm") @FormParam("confirm") Boolean confirm + @Parameter(required = true, description = "The SID of the User. This SID must be marked as Loggedin") @WebParam(name="sid") @QueryParam("sid") String sid + , @Parameter(required = true, description = "user object") @WebParam(name="user") @FormParam("user") UserDTO user + , @Parameter(required = true, description = "whatever or not to send email, leave empty for auto-send") @WebParam(name="confirm") @FormParam("confirm") Boolean confirm ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -245,8 +277,16 @@ public class UserWebService extends BaseWebService { @WebMethod @DELETE @Path("/{id}") - public ServiceResult delete(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="id") @PathParam("id") long id + @Operation( + description = "Delete a certain user by its id", + responses = { + @ApiResponse(responseCode = "200", description = "id of the user deleted, error code otherwise", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") + } + ) + public ServiceResult delete( + @Parameter(required = true, description = "The SID of the User. This SID must be marked as Loggedin") @WebParam(name="sid") @QueryParam("sid") String sid + , @Parameter(required = true, description = "the openmeetings user id") @WebParam(name="id") @PathParam("id") long id ) throws ServiceException { return performCall(sid, User.Right.ADMIN, sd -> { @@ -265,17 +305,24 @@ public class UserWebService extends BaseWebService { * @param externalId * externalUserId * @param externalType - * externalUserId + * externalType * * @return - id of user deleted, or error code * @throws {@link ServiceException} in case of any errors */ @DELETE @Path("/{externaltype}/{externalid}") + @Operation( + description = "Delete a certain user by its external user id", + responses = { + @ApiResponse(responseCode = "200", description = "id of user deleted, or error code", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") + } + ) public ServiceResult deleteExternal( - @WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="externaltype") @PathParam("externaltype") String externalType - , @WebParam(name="externalid") @PathParam("externalid") String externalId + @Parameter(required = true, description = "The SID of the User. This SID must be marked as Loggedin") @WebParam(name="sid") @QueryParam("sid") String sid + , @Parameter(required = true, description = "externalUserId") @WebParam(name="externaltype") @PathParam("externaltype") String externalType + , @Parameter(required = true, description = "externalType") @WebParam(name="externalid") @PathParam("externalid") String externalId ) throws ServiceException { return performCall(sid, User.Right.ADMIN, sd -> { @@ -289,7 +336,7 @@ public class UserWebService extends BaseWebService { } /** - * Description: sets the SessionObject for a certain SID, after setting this + * Sets the SessionObject for a certain SID, after setting this * Session-Object you can use the SID + a RoomId to enter any Room. ... * Session-Hashs are deleted 15 minutes after the creation if not used. * @@ -306,10 +353,19 @@ public class UserWebService extends BaseWebService { @WebMethod @POST @Path("/hash") + @Operation( + description = "Sets the SessionObject for a certain SID, after setting this\n" + + " Session-Object you can use the SID + a RoomId to enter any Room. ...\n" + + " Session-Hashs are deleted 15 minutes after the creation if not used.", + responses = { + @ApiResponse(responseCode = "200", description = "secure hash or error code", content = @Content(schema = @Schema(implementation = ServiceResult.class))), + @ApiResponse(responseCode = "500", description = "Error in case of invalid credentials or server error") + } + ) public ServiceResult getRoomHash( - @WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="user") @FormParam("user") ExternalUserDTO user - , @WebParam(name="options") @FormParam("options") RoomOptionsDTO options + @Parameter(required = true, description = "The SID of the User. This SID must be marked as Loggedin") @WebParam(name="sid") @QueryParam("sid") String sid + , @Parameter(required = true, description = "user details to set") @WebParam(name="user") @FormParam("user") ExternalUserDTO user + , @Parameter(required = true, description = "room options to set") @WebParam(name="options") @FormParam("options") RoomOptionsDTO options ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> {
