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/04 01:06:49 UTC
[openmeetings] 01/01: OPENMEETINGS-2660 Update response codes and
objects to be generated. Add UserService API tags for documentation.
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 <se...@gmail.com>
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 -> {