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:17 UTC
[openmeetings] branch
feature/OPENMEETINGS-2420-update-swagger-rest-api-docs-RoomService created
(now dcb1235)
This is an automated email from the ASF dual-hosted git repository.
sebawagner pushed a change to branch feature/OPENMEETINGS-2420-update-swagger-rest-api-docs-RoomService
in repository https://gitbox.apache.org/repos/asf/openmeetings.git.
at dcb1235 Merge branch 'master' into feature/OPENMEETINGS-2420-update-swagger-rest-api-docs-RoomService
This branch includes the following new commits:
new 7db3f9a OPENMEETINGS-2420 Update Rest API docs for RoomService.
new dcb1235 Merge branch 'master' into feature/OPENMEETINGS-2420-update-swagger-rest-api-docs-RoomService
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[openmeetings] 02/02: Merge branch 'master' into
feature/OPENMEETINGS-2420-update-swagger-rest-api-docs-RoomService
Posted by se...@apache.org.
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 dcb1235895a71985f8f541a790011d096231d45e
Merge: 7db3f9a 2f802e9
Author: Sebastian Wagner <se...@gmail.com>
AuthorDate: Fri Sep 3 17:27:51 2021 +1200
Merge branch 'master' into feature/OPENMEETINGS-2420-update-swagger-rest-api-docs-RoomService
.../test/java/org/apache/openmeetings/web/TestCalendar.java | 2 +-
.../org/apache/openmeetings/webservice/NetTestWebService.java | 2 +-
pom.xml | 10 ++++++++--
3 files changed, 10 insertions(+), 4 deletions(-)
[openmeetings] 01/02: OPENMEETINGS-2420 Update Rest API docs for
RoomService.
Posted by se...@apache.org.
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