This is an automated email from the ASF dual-hosted git repository. sebawagner pushed a commit to branch feature/OPENMEETINGS-2420-update-swagger-rest-api-docs-RoomService in repository https://gitbox.apache.org/repos/asf/openmeetings.git
commit 7db3f9a2584f947b86ef95c9eb9852f3ce3932af Author: Sebastian Wagner <[email protected]> AuthorDate: Fri Sep 3 17:27:03 2021 +1200 OPENMEETINGS-2420 Update Rest API docs for RoomService. --- openmeetings-webservice/pom.xml | 6 + .../openmeetings/webservice/RoomWebService.java | 167 +++++++++++++++++---- 2 files changed, 141 insertions(+), 32 deletions(-) diff --git a/openmeetings-webservice/pom.xml b/openmeetings-webservice/pom.xml index e4e8ed3..5649a7d 100644 --- a/openmeetings-webservice/pom.xml +++ b/openmeetings-webservice/pom.xml @@ -81,6 +81,12 @@ <name>The Apache Software License, Version 2.0</name> </license> </info> + <servers> + <server> + <description>Om Demo Server</description> + <url>https://om.alteametasoft.com/openmeetings/services</url> + </server> + </servers> </swaggerConfig> </configuration> <executions> 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 452eda5..47cbce1 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 @@ -64,7 +64,10 @@ import org.slf4j.LoggerFactory; 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.tags.Tag; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.responses.ApiResponse; /** * RoomService contains methods to manipulate rooms and create invitation hash @@ -110,8 +113,18 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/public/{type}") - public List<RoomDTO> getPublic(@QueryParam("sid") @WebParam(name="sid") String sid - , @PathParam("type") @WebParam(name="type") String type + @Operation( + description = "Returns an Object of Type RoomsList which contains a list of\n" + + " ROOM-Objects. Every ROOM-Object contains a Roomtype and all informations\n" + + " 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") + } + ) + public List<RoomDTO> getPublic( + @Parameter(required = true, description = "The SID of the User. This SID must be marked as Loggedin") @QueryParam("sid") @WebParam(name="sid") String sid + , @Parameter(required = true, description = "Type of public rooms need to be retrieved") @PathParam("type") @WebParam(name="type") String type ) throws ServiceException { Room.Type t = Strings.isEmpty(type) ? null : Room.Type.valueOf(type); @@ -129,8 +142,15 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/{id}") - public RoomDTO getRoomById(@QueryParam("sid") @WebParam(name="sid") String sid - , @PathParam("id") @WebParam(name="id") Long id + @Operation( + description = "Returns a conference room object", + responses = { + @ApiResponse(responseCode = "200", description = "room with the id given") + } + ) + public RoomDTO getRoomById( + @Parameter(required = true, description = "The SID of the User. This SID must be marked as Loggedin") @QueryParam("sid") @WebParam(name="sid") String sid + , @Parameter(required = true, description = "the room id") @PathParam("id") @WebParam(name="id") Long id ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> new RoomDTO(roomDao.get(id))); @@ -178,11 +198,20 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/{type}/{externaltype}/{externalid}") - public RoomDTO getExternal(@WebParam(name="sid") @QueryParam("sid") String sid - , @PathParam("type") @WebParam(name="type") String type - , @PathParam("externaltype") @WebParam(name="externaltype") String externalType - , @PathParam("externalid") @WebParam(name="externalid") String externalId - , @WebParam(name="room") @QueryParam("room") RoomDTO room + @Operation( + description = "Checks if a room with this exteralId + externalType does exist,\n" + + " 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") + } + ) + public RoomDTO getExternal( + @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 = "type of the room") @PathParam("type") @WebParam(name="type") String type + , @Parameter(required = true, description = "you can specify your system-name or type of room here, for example \"moodle\"") @PathParam("externaltype") @WebParam(name="externaltype") String externalType + , @Parameter(required = true, description = "your external room id may set here") @PathParam("externalid") @WebParam(name="externalid") String externalId + , @Parameter(required = true, description = "details of the room to be created if not found") @WebParam(name="room") @QueryParam("room") RoomDTO room ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -211,14 +240,21 @@ public class RoomWebService extends BaseWebService { * @param room * room object * - * @return - id of the USER added or error code + * @return - Room object or throw error * @throws {@link ServiceException} in case of any errors */ @WebMethod @POST @Path("/") - public RoomDTO add(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="room") @FormParam("room") RoomDTO room + @Operation( + description = "Adds a new ROOM like through the Frontend", + responses = { + @ApiResponse(responseCode = "200", description = "Room object or throw error") + } + ) + public RoomDTO add( + @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 = "room object") @WebParam(name="room") @FormParam("room") RoomDTO room ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -240,8 +276,15 @@ public class RoomWebService 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 room by its room id", + responses = { + @ApiResponse(responseCode = "200", description = "id of the room deleted") + } + ) + 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 id of the room") @WebParam(name="id") @PathParam("id") long id ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -273,8 +316,17 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/close/{id}") - public ServiceResult close(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="id") @PathParam("id") long id + @Operation( + description = "Method to remotely close rooms. If a room is closed all users\n" + + " 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") + } + ) + public ServiceResult close( + @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 room id") @WebParam(name="id") @PathParam("id") long id ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -308,8 +360,17 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/open/{id}") - public ServiceResult open(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="id") @PathParam("id") long id + @Operation( + description = "Method to remotely open rooms. If a room is closed all users\n" + + " 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") + } + ) + public ServiceResult open( + @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 room id") @WebParam(name="id") @PathParam("id") long id ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -335,8 +396,15 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/kick/{id}") - public ServiceResult kickAll(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="id") @PathParam("id") long id + @Operation( + description = "Kick all uses of a certain room", + responses = { + @ApiResponse(responseCode = "200", description = "true if USER was kicked, false otherwise") + } + ) + public ServiceResult kickAll( + @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 room id") @WebParam(name="id") @PathParam("id") long id ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -357,16 +425,23 @@ public class RoomWebService extends BaseWebService { * @param externalId * external id of USER to kick * - * @return - true if USER was kicked, false otherwise + * @return - 'Kicked' if USER was 'Not kicked' otherwise * @throws {@link ServiceException} in case of any errors */ @WebMethod @GET @Path("/kick/{id}/{externalType}/{externalId}") - public ServiceResult kick(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="id") @PathParam("id") long id - , @WebParam(name="externalType") @PathParam("externalType") String externalType - , @WebParam(name="externalId") @PathParam("externalId") String externalId + @Operation( + description = "kick external USER from given room", + responses = { + @ApiResponse(responseCode = "200", description = "'Kicked' if USER was 'Not kicked' otherwise") + } + ) + public ServiceResult kick( + @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 room id") @WebParam(name="id") @PathParam("id") long id + , @Parameter(required = true, description = "external type of USER to kick") @WebParam(name="externalType") @PathParam("externalType") String externalType + , @Parameter(required = true, description = "external id of USER to kick") @WebParam(name="externalId") @PathParam("externalId") String externalId ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -385,8 +460,15 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/count/{roomid}") - public ServiceResult count(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="roomid") @PathParam("roomid") Long roomId + @Operation( + description = "Returns the count of users currently in the ROOM with given id", + responses = { + @ApiResponse(responseCode = "200", description = "number of users as int") + } + ) + public ServiceResult count( + @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 = "roomId id of the room to get users") @WebParam(name="roomid") @PathParam("roomid") Long roomId ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> new ServiceResult(String.valueOf(clientManager.streamByRoom(roomId).count()), Type.SUCCESS)); @@ -403,8 +485,15 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/users/{roomid}") - public List<UserDTO> users(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="roomid") @PathParam("roomid") Long roomId + @Operation( + description = "Returns list of users currently in the ROOM with given id", + responses = { + @ApiResponse(responseCode = "200", description = "List of users in the room") + } + ) + public List<UserDTO> users( + @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 = "roomId id of the room to get users") @WebParam(name="roomid") @PathParam("roomid") Long roomId ) throws ServiceException { return performCall(sid, User.Right.SOAP, sd -> { @@ -426,9 +515,16 @@ public class RoomWebService extends BaseWebService { @WebMethod @POST @Path("/hash") - public ServiceResult hash(@WebParam(name="sid") @QueryParam("sid") String sid - , @WebParam(name="invite") @QueryParam("invite") InvitationDTO invite - , @WebParam(name="sendmail") @QueryParam("sendmail") boolean sendmail + @Operation( + description = "Method to get invitation hash with given parameters", + responses = { + @ApiResponse(responseCode = "200", description = "serviceResult object with the result") + } + ) + public ServiceResult hash( + @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 = "parameters of the invitation") @WebParam(name="invite") @QueryParam("invite") InvitationDTO invite + , @Parameter(required = true, description = "flag to determine if email should be sent or not") @WebParam(name="sendmail") @QueryParam("sendmail") boolean sendmail ) throws ServiceException { log.debug("[hash] invite {}", invite); @@ -465,6 +561,13 @@ public class RoomWebService extends BaseWebService { @WebMethod @GET @Path("/cleanwb/{id}") + @Operation( + 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") + } + ) public ServiceResult cleanWb(@WebParam(name="sid") @QueryParam("sid") String sid , @WebParam(name="id") @PathParam("id") long id ) throws ServiceException
