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:48 UTC
[openmeetings] branch
feature/OPENMEETINGS-2660-update-swagger-rest-api-docs-additional-Web-Services
created (now 55fcb94)
This is an automated email from the ASF dual-hosted git repository.
sebawagner pushed a change to branch feature/OPENMEETINGS-2660-update-swagger-rest-api-docs-additional-Web-Services
in repository https://gitbox.apache.org/repos/asf/openmeetings.git.
at 55fcb94 OPENMEETINGS-2660 Update response codes and objects to be generated. Add UserService API tags for documentation.
This branch includes the following new commits:
new 55fcb94 OPENMEETINGS-2660 Update response codes and objects to be generated. Add UserService API tags for documentation.
The 1 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] 01/01: OPENMEETINGS-2660 Update response codes and
objects to be generated. Add UserService API tags for documentation.
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-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 -> {