You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openmeetings.apache.org by se...@apache.org on 2021/09/03 05:28:18 UTC
[openmeetings] 01/02: OPENMEETINGS-2420 Update Rest API docs for
RoomService.
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 <se...@gmail.com>
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