diff --git a/changelog.html b/changelog.html
index aefb2217b..bf94c4349 100644
--- a/changelog.html
+++ b/changelog.html
@@ -47,6 +47,7 @@
1.12.1 (to be determined)
- Now requires Openfire 5.1.0 or later
+ - [#269] - Improve completeness, accuracy and consistency of the OpenAPI documentation
- [#265] - Ensure cross-database compatibility for unread message count query
- [#261] - Remove the deprecated 'userservice' endpoint
- [#259] - Prevent system property requests from affecting properties other than the one requested
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/ClusteringService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/ClusteringService.java
index 52073f25d..54a72d63d 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/ClusteringService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/ClusteringService.java
@@ -27,6 +27,7 @@
import org.jivesoftware.openfire.cluster.NodeID;
import org.jivesoftware.openfire.plugin.rest.controller.ClusteringController;
import org.jivesoftware.openfire.plugin.rest.controller.MUCRoomController;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.entity.*;
import org.jivesoftware.openfire.plugin.rest.exceptions.ExceptionType;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
@@ -39,7 +40,7 @@
import java.util.Optional;
@Path("restapi/v1/clustering")
-@Tag(name="Clustering", description = "Reporting the status of Openfire clustering")
+@Tag(name="Clustering", description = "Reporting the status of Openfire clustering.")
public class ClusteringService {
private ClusteringController clusteringController;
@@ -52,9 +53,11 @@ public void init() {
@GET
@Path("/status")
@Operation( summary = "Get clustering status",
- description = "Describes the point-in-time state of Openfire's clustering with other servers",
+ description = "Describes the point-in-time state of Openfire's clustering with other servers.",
responses = {
- @ApiResponse(responseCode = "200", description = "Status returned", content = @Content(schema = @Schema(implementation = ClusteringEntity.class)))
+ @ApiResponse(responseCode = "200", description = "Status returned.", content = @Content(schema = @Schema(implementation = ClusteringEntity.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public ClusteringEntity getClusteringStatus(){
@@ -66,7 +69,9 @@ public ClusteringEntity getClusteringStatus(){
@Operation( summary = "Get all cluster nodes",
description = "Get a list of all nodes of the cluster. Note that this endpoint can only return data for remote nodes when the instance of Openfire that processes this query has successfully joined the cluster.",
responses = {
- @ApiResponse(responseCode = "200", description = "Retrieve all cluster nodes", content = @Content(schema = @Schema(implementation = ClusterNodeEntities.class)))
+ @ApiResponse(responseCode = "200", description = "All cluster nodes.", content = @Content(schema = @Schema(implementation = ClusterNodeEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public ClusterNodeEntities getClusterNodes() {
@@ -78,8 +83,10 @@ public ClusterNodeEntities getClusterNodes() {
@Operation( summary = "Get a specific cluster node",
description = "Get a specific node of the cluster. Note that this endpoint can only return data for remote nodes when the instance of Openfire that processes this query has successfully joined the cluster.",
responses = {
- @ApiResponse(responseCode = "200", description = "Retrieve a cluster node", content = @Content(schema = @Schema(implementation = ClusterNodeEntity.class))),
- @ApiResponse(responseCode = "404", description = "The provided NodeID does not identify an existing cluster node.")
+ @ApiResponse(responseCode = "200", description = "The cluster node.", content = @Content(schema = @Schema(implementation = ClusterNodeEntity.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "The provided NodeID does not identify an existing cluster node.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public ClusterNodeEntity getClusterNode(@Parameter(description = "The nodeID value for a particular node.", example = "52a89928-66f7-45fd-9bb8-096de07400ac", required = true) @PathParam("nodeId") final String nodeId) throws ServiceException {
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/GroupService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/GroupService.java
index f1b452b15..38c758ce5 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/GroupService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/GroupService.java
@@ -26,6 +26,7 @@
import org.jivesoftware.openfire.plugin.rest.controller.GroupController;
import org.jivesoftware.openfire.plugin.rest.entity.GroupEntities;
import org.jivesoftware.openfire.plugin.rest.entity.GroupEntity;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -34,7 +35,7 @@
import javax.ws.rs.core.Response;
@Path("restapi/v1/groups")
-@Tag(name="User Group", description = "Managing Openfire user groupings.")
+@Tag(name="User Group", description = "Managing Openfire user groups.")
public class GroupService {
private GroupController groupController;
@@ -48,7 +49,9 @@ public void init() {
@Operation( summary = "Get groups",
description = "Get a list of all user groups.",
responses = {
- @ApiResponse(responseCode = "200", description = "All groups", content = @Content(schema = @Schema(implementation = GroupEntities.class)))
+ @ApiResponse(responseCode = "200", description = "All groups.", content = @Content(schema = @Schema(implementation = GroupEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public GroupEntities getGroups() throws ServiceException
@@ -61,8 +64,10 @@ public GroupEntities getGroups() throws ServiceException
description = "Create a new user group.",
responses = {
@ApiResponse(responseCode = "201", description = "Group created."),
- @ApiResponse(responseCode = "400", description = "Group or group name missing, or invalid syntax for a property."),
- @ApiResponse(responseCode = "409", description = "Group already exists.")
+ @ApiResponse(responseCode = "400", description = "Group or group name missing, or invalid syntax for a property.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "409", description = "Group already exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public Response createGroup(
@@ -79,7 +84,9 @@ public Response createGroup(
description = "Get one specific user group by name.",
responses = {
@ApiResponse(responseCode = "200", description = "The group.", content = @Content(schema = @Schema(implementation = GroupEntity.class))),
- @ApiResponse(responseCode = "404", description = "Group with this name not found.")
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "Group with this name not found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public GroupEntity getGroup(@Parameter(description = "The name of the group that needs to be fetched.", example = "Colleagues", required = true) @PathParam("groupName") String groupName)
@@ -94,11 +101,13 @@ public GroupEntity getGroup(@Parameter(description = "The name of the group that
description = "Updates / overwrites an existing user group. Note that the name of the group cannot be changed.",
responses = {
@ApiResponse(responseCode = "200", description = "Group updated."),
- @ApiResponse(responseCode = "400", description = "Group or group name missing, or name does not match existing group, or invalid syntax for a property."),
- @ApiResponse(responseCode = "404", description = "Group with this name not found."),
+ @ApiResponse(responseCode = "400", description = "Group or group name missing, or name does not match existing group, or invalid syntax for a property.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "Group with this name not found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
- public Response updateGroup(@Parameter(description = "The name of the group that needs to be fetched.", example = "Colleagues", required = true) @PathParam("groupName") String groupName,
+ public Response updateGroup(@Parameter(description = "The name of the group that needs to be updated.", example = "Colleagues", required = true) @PathParam("groupName") String groupName,
@RequestBody(description = "The new group definition that needs to overwrite the old definition.", required = true) GroupEntity groupEntity )
throws ServiceException
{
@@ -112,7 +121,9 @@ public Response updateGroup(@Parameter(description = "The name of the group that
description = "Removes an existing user group.",
responses = {
@ApiResponse(responseCode = "200", description = "Group deleted."),
- @ApiResponse(responseCode = "400", description = "Group not found.")
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "Group with this name not found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response deleteGroup(@Parameter(description = "The name of the group that needs to be removed.", example = "Colleagues", required = true) @PathParam("groupName") String groupName)
throws ServiceException
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomAffiliationsService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomAffiliationsService.java
index 26871445f..4fff80d7e 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomAffiliationsService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomAffiliationsService.java
@@ -40,25 +40,25 @@
import java.util.stream.Collectors;
@Path("restapi/v1/chatrooms/{roomName}/{affiliation: (admins|members|outcasts|owners)}")
-@Tag(name = "Chat room", description = "Managing Multi-User chat rooms.")
+@Tag(name = "Chat room", description = "Managing multi-user chat rooms.")
public class MUCRoomAffiliationsService
{
-
@GET
@Path("/")
- @Operation( summary = "All room affiliations",
- description = "Retrieves a list of JIDs for all affiliated users of a multi-user chat room.",
+ @Operation( summary = "Get room affiliations",
+ description = "Retrieves a list of JIDs for all users that have a particular affiliation with a multi-user chat room.",
responses = {
- @ApiResponse(responseCode = "200", description = "Affiliated user list retrieved."),
- @ApiResponse(responseCode = "400", description = "Provided 'affiliations' value is invalid."),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "Affiliated user list retrieved.", content = @Content(schema = @Schema(oneOf = { AdminEntities.class, MemberEntities.class, OutcastEntities.class, OwnerEntities.class }))),
+ @ApiResponse(responseCode = "400", description = "Provided 'affiliations' value is invalid.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
+ @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public Response getAffiliations(
@Parameter(description = "The name of the MUC service that the MUC room is part of.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@Parameter(description = "The name of the MUC room for which to return affiliations.", example = "lobby", required = true) @PathParam("roomName") String roomName,
- @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners' .", example = "members", required = true) @PathParam("affiliation") String affiliations)
+ @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners'.", example = "members", required = true) @PathParam("affiliation") String affiliations)
throws ServiceException
{
roomName = JID.nodeprep(roomName);
@@ -99,7 +99,7 @@ public Response getAffiliations(
responses = {
@ApiResponse(responseCode = "201", description = "Affiliations of the room have been replaced."),
@ApiResponse(responseCode = "400", description = "Provided values cannot be parsed as JIDs, or provided 'affiliations' value is invalid.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to perform this affiliation change.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
@@ -108,8 +108,8 @@ public Response getAffiliations(
public Response replaceMUCRoomAffiliation(
@Parameter(description = "The name of the MUC service that the MUC room is part of.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@Parameter(description = "The name of the MUC room of which affiliations are to be replaced.", example = "lobby", required = true) @PathParam("roomName") String roomName,
- @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners' .", example = "members", required = true) @PathParam("affiliation") String affiliations,
- @Parameter(description = "Whether to send invitations to new admin users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
+ @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners'.", example = "members", required = true) @PathParam("affiliation") String affiliations,
+ @Parameter(description = "Whether to send invitations to newly affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
@RequestBody(description = "The new list of users with this particular affiliation.", required = true) AffiliatedEntities affiliatedEntities)
throws ServiceException
{
@@ -127,11 +127,11 @@ public Response replaceMUCRoomAffiliation(
@POST
@Path("/")
@Operation( summary = "Add room affiliations",
- description = "Affiliatione multiple users to a particular multi-user chat room (without removing existing affiliated users of that type). Note that a user can only have one type of affiliation with a room. By affiliating a user to a room, any other pre-existing affiliation for that user is removed.",
+ description = "Affiliates multiple users to a particular multi-user chat room (without removing existing affiliated users of that type). Note that a user can only have one type of affiliation with a room. By affiliating a user to a room, any other pre-existing affiliation for that user is removed.",
responses = {
@ApiResponse(responseCode = "201", description = "Users have been affiliated to the room."),
@ApiResponse(responseCode = "400", description = "Provided values cannot be parsed as JIDs, or provided 'affiliations' value is invalid.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to perform this affiliation change.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
@@ -140,8 +140,8 @@ public Response replaceMUCRoomAffiliation(
public Response addMUCRoomAffiliations(
@Parameter(description = "The name of the MUC service that the MUC room is part of.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@Parameter(description = "The name of the MUC room to which users are to be affiliated.", example = "lobby", required = true) @PathParam("roomName") String roomName,
- @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners' .", example = "members", required = true) @PathParam("affiliation") String affiliations,
- @Parameter(description = "Whether to send invitations to new admin users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
+ @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners'.", example = "members", required = true) @PathParam("affiliation") String affiliations,
+ @Parameter(description = "Whether to send invitations to newly affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
@RequestBody(description = "The list of users to affiliate to the room.", required = true) AffiliatedEntities affiliatedEntities)
throws ServiceException
{
@@ -159,11 +159,11 @@ public Response addMUCRoomAffiliations(
@POST
@Path("/{jid}")
@Operation( summary = "Add room affiliation",
- description = "Affiliates a single use to a multi-user chat room. Note that a user can only have one type of affiliation with a room. By affiliating a user to a room, any other pre-existing affiliation for that user is removed.",
+ description = "Affiliates a single user to a multi-user chat room. Note that a user can only have one type of affiliation with a room. By affiliating a user to a room, any other pre-existing affiliation for that user is removed.",
responses = {
- @ApiResponse(responseCode = "201", description = "User to affiliate to the room."),
+ @ApiResponse(responseCode = "201", description = "User has been affiliated to the room."),
@ApiResponse(responseCode = "400", description = "Provided 'affiliations' value is invalid.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to perform this affiliation change.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
@@ -171,9 +171,9 @@ public Response addMUCRoomAffiliations(
public Response addMUCRoomAffiliation(
@Parameter(description = "The name of the MUC service that the MUC room is part of.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@Parameter(description = "The (bare) JID of the entity that is to be affiliated.", example = "john@example.org", required = true) @PathParam("jid") String jid,
- @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners' .", example = "members", required = true) @PathParam("affiliation") String affiliations,
+ @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners'.", example = "members", required = true) @PathParam("affiliation") String affiliations,
@Parameter(description = "The name of the MUC room to which an affiliation is to be added.", example = "lobby", required = true) @PathParam("roomName") String roomName,
- @Parameter(description = "Whether to send invitations to new admin users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations)
+ @Parameter(description = "Whether to send invitations to newly affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations)
throws ServiceException
{
roomName = JID.nodeprep(roomName);
@@ -189,12 +189,12 @@ public Response addMUCRoomAffiliation(
@POST
@Path("/group/{groupname}")
- @Operation( summary = "Add room affiliations",
+ @Operation( summary = "Add group room affiliations",
description = "Affiliate all members of an Openfire user group to a multi-user chat room. Note that a user can only have one type of affiliation with a room. By affiliating a user to a room, any other pre-existing affiliation for that user is removed.",
responses = {
@ApiResponse(responseCode = "201", description = "Affiliations added to the room."),
@ApiResponse(responseCode = "400", description = "Provided 'affiliations' value is invalid.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to perform this affiliation change.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
@@ -202,9 +202,9 @@ public Response addMUCRoomAffiliation(
public Response addMUCRoomAffiliationGroup(
@Parameter(description = "The name of the MUC service that the MUC room is part of.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@Parameter(description = "The name of the user group from which all members will be affiliated to the room.", example = "Operators", required = true) @PathParam("groupname") String groupname,
- @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners' .", example = "members", required = true) @PathParam("affiliation") String affiliations,
+ @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners'.", example = "members", required = true) @PathParam("affiliation") String affiliations,
@Parameter(description = "The name of the MUC room to which affiliations are to be added.", example = "lobby", required = true) @PathParam("roomName") String roomName,
- @Parameter(description = "Whether to send invitations to new admin users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations)
+ @Parameter(description = "Whether to send invitations to newly affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations)
throws ServiceException
{
roomName = JID.nodeprep(roomName);
@@ -225,7 +225,7 @@ public Response addMUCRoomAffiliationGroup(
responses = {
@ApiResponse(responseCode = "200", description = "Affiliation removed from the room."),
@ApiResponse(responseCode = "400", description = "Provided 'affiliations' value is invalid.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to remove this affiliation.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "409", description = "Applying this affiliation change would cause a room conflict.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@@ -234,7 +234,7 @@ public Response addMUCRoomAffiliationGroup(
public Response deleteMUCRoomAffiliation(
@Parameter(description = "The (bare) JID of the entity for which the room affiliation is to be removed.", example = "john@example.org", required = true) @PathParam("jid") String jid,
@Parameter(description = "The name of the MUC service that the MUC room is part of.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
- @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners' .", example = "members", required = true) @PathParam("affiliation") String affiliations,
+ @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners'.", example = "members", required = true) @PathParam("affiliation") String affiliations,
@Parameter(description = "The name of the MUC room from which an affiliation is to be removed.", example = "lobby", required = true) @PathParam("roomName") String roomName)
throws ServiceException
{
@@ -251,12 +251,12 @@ public Response deleteMUCRoomAffiliation(
@DELETE
@Path("/group/{groupname}")
- @Operation( summary = "Remove room affiliations",
+ @Operation( summary = "Remove group room affiliations",
description = "Removes affiliation for all members of an Openfire user group from a multi-user chat room.",
responses = {
@ApiResponse(responseCode = "200", description = "Affiliations removed from the room."),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "400", description = "Provided 'affiliations' value is invalid.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to remove this affiliation.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "409", description = "Applying this affiliation change would cause a room conflict.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@@ -265,7 +265,7 @@ public Response deleteMUCRoomAffiliation(
public Response deleteMUCRoomAffiliationGroup(
@Parameter(description = "The name of the user group from which all members will get their room affiliation removed.", example = "Operators", required = true) @PathParam("groupname") String groupname,
@Parameter(description = "The name of the MUC service that the MUC room is part of.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
- @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners' .", example = "members", required = true) @PathParam("affiliation") String affiliations,
+ @Parameter(description = "The type of affiliation. One of: 'admins', 'members', 'outcasts', 'owners'.", example = "members", required = true) @PathParam("affiliation") String affiliations,
@Parameter(description = "The name of the MUC room from which affiliations are to be removed.", example = "lobby", required = true) @PathParam("roomName") String roomName)
throws ServiceException
{
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomService.java
index 876b246c5..fdef79aab 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomService.java
@@ -36,23 +36,23 @@
import javax.ws.rs.core.Response.Status;
@Path("restapi/v1/chatrooms")
-@Tag(name = "Chat room", description = "Managing Multi-User chat rooms.")
+@Tag(name = "Chat room", description = "Managing multi-user chat rooms.")
public class MUCRoomService {
@GET
@Operation( summary = "Get chat rooms",
description = "Get a list of all multi-user chat rooms of a particular chat room service.",
responses = {
- @ApiResponse(responseCode = "200", description = "All chat rooms", content = @Content(schema = @Schema(implementation = MUCRoomEntities.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "All chat rooms.", content = @Content(schema = @Schema(implementation = MUCRoomEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "404", description = "MUC service does not exist or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public MUCRoomEntities getMUCRooms(
@Parameter(description = "The name of the MUC service for which to return all chat rooms.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
- @Parameter(description = "Room type-based filter: 'all' or 'public'", examples = { @ExampleObject(value = "public", description = "Only return rooms configured with 'List Room in Directory'"), @ExampleObject(value = "all", description = "Return all rooms")}, required = false) @DefaultValue(MUCChannelType.PUBLIC) @QueryParam("type") String channelType,
- @Parameter(description = "Search/Filter by room name.\nThis act like the wildcard search %String%", example = "conference", required = false) @QueryParam("search") String roomSearch,
+ @Parameter(description = "Room type-based filter: 'all' or 'public'.", examples = { @ExampleObject(value = "public", description = "Only return rooms configured with 'List Room in Directory'"), @ExampleObject(value = "all", description = "Return all rooms")}, required = false) @DefaultValue(MUCChannelType.PUBLIC) @QueryParam("type") String channelType,
+ @Parameter(description = "Search/Filter by room name.\nThis acts like the wildcard search %String%", example = "conference", required = false) @QueryParam("search") String roomSearch,
@Parameter(description = "For all groups defined in owners, admins, members and outcasts, list individual members instead of the group name.", required = false) @DefaultValue("false") @QueryParam("expandGroups") Boolean expand)
throws ServiceException
{
@@ -64,8 +64,8 @@ public MUCRoomEntities getMUCRooms(
@Operation( summary = "Get chat room",
description = "Get information of a specific multi-user chat room.",
responses = {
- @ApiResponse(responseCode = "200", description = "The chat room", content = @Content(schema = @Schema(implementation = MUCRoomEntity.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "The chat room.", content = @Content(schema = @Schema(implementation = MUCRoomEntity.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@@ -84,7 +84,7 @@ public MUCRoomEntity getMUCRoomJSON2(
description = "Removes an existing multi-user chat room.",
responses = {
@ApiResponse(responseCode = "200", description = "Room deleted."),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@@ -105,16 +105,16 @@ public Response deleteMUCRoom(
description = "Create a new multi-user chat room.",
responses = {
@ApiResponse(responseCode = "201", description = "Room created."),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Room creation is not permitted.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "404", description = "MUC Service does not exist or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "404", description = "MUC service does not exist or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "409", description = "Room already exists, or another conflict occurred while creating the room.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public Response createMUCRoom(
@Parameter(description = "The name of the MUC service in which to create a chat room.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
- @Parameter(description = "Whether to send invitations to affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
+ @Parameter(description = "Whether to send invitations to newly affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
@RequestBody(description = "The MUC room that needs to be created.", required = true) MUCRoomEntity mucRoomEntity)
throws ServiceException
{
@@ -128,14 +128,14 @@ public Response createMUCRoom(
description = "Create a number of new multi-user chat rooms.",
responses = {
@ApiResponse(responseCode = "200", description = "Request has been processed. Results are reported in the response.", content = @Content(schema = @Schema(implementation = RoomCreationResultEntities.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "404", description = "MUC Service does not exist or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "MUC service does not exist or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public RoomCreationResultEntities createMUCRooms(
- @Parameter(description = "The name of the MUC service in which to create a chat room.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
+ @Parameter(description = "The name of the MUC service in which to create the chat rooms.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@Parameter(description = "Whether to send invitations to newly affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
@RequestBody(description = "The MUC rooms that need to be created.", required = true) MUCRoomEntities mucRoomEntities)
throws ServiceException
@@ -149,15 +149,15 @@ public RoomCreationResultEntities createMUCRooms(
description = "Updates an existing multi-user chat room.",
responses = {
@ApiResponse(responseCode = "200", description = "Room updated."),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Room update/create is not permitted.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
- @ApiResponse(responseCode = "404", description = "MUC Service does not exist or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "404", description = "MUC service does not exist or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "409", description = "This update causes a conflict, possibly with another existing room.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public Response updateMUCRoom(
- @Parameter(description = "The name of the chat room that needs to be updated", example = "lobby", required = true) @PathParam("roomName") String roomName,
+ @Parameter(description = "The name of the chat room that needs to be updated.", example = "lobby", required = true) @PathParam("roomName") String roomName,
@Parameter(description = "The name of the MUC service in which to update a chat room.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@Parameter(description = "Whether to send invitations to newly affiliated users.", example = "true", required = false) @DefaultValue("false") @QueryParam("sendInvitations") boolean sendInvitations,
@RequestBody(description = "The new MUC room definition that needs to overwrite the old definition.", required = true) MUCRoomEntity mucRoomEntity)
@@ -173,14 +173,14 @@ public Response updateMUCRoom(
@Operation( summary = "Get room participants",
description = "Get all participants of a specific multi-user chat room.",
responses = {
- @ApiResponse(responseCode = "200", description = "The chat room participants", content = @Content(schema = @Schema(implementation = ParticipantEntities.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "The chat room participants.", content = @Content(schema = @Schema(implementation = ParticipantEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public ParticipantEntities getMUCRoomParticipants(
- @Parameter(description = "The name of the chat room for which to return participants", example = "lobby", required = true) @PathParam("roomName") String roomName,
+ @Parameter(description = "The name of the chat room for which to return participants.", example = "lobby", required = true) @PathParam("roomName") String roomName,
@Parameter(description = "The name of the chat room's MUC service.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName)
throws ServiceException
{
@@ -193,14 +193,14 @@ public ParticipantEntities getMUCRoomParticipants(
@Operation( summary = "Get room occupants",
description = "Get all occupants of a specific multi-user chat room.",
responses = {
- @ApiResponse(responseCode = "200", description = "The chat room participants", content = @Content(schema = @Schema(implementation = OccupantEntities.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "The chat room occupants.", content = @Content(schema = @Schema(implementation = OccupantEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public OccupantEntities getMUCRoomOccupants(
- @Parameter(description = "The name of the chat room for which to return occupants", example = "lobby", required = true) @PathParam("roomName") String roomName,
+ @Parameter(description = "The name of the chat room for which to return occupants.", example = "lobby", required = true) @PathParam("roomName") String roomName,
@Parameter(description = "The name of the chat room's MUC service.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName)
throws ServiceException
{
@@ -213,14 +213,14 @@ public OccupantEntities getMUCRoomOccupants(
@Operation( summary = "Get room history",
description = "Get messages that have been exchanged in a specific multi-user chat room.",
responses = {
- @ApiResponse(responseCode = "200", description = "The chat room message history", content = @Content(schema = @Schema(implementation = MUCRoomMessageEntities.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "The chat room message history.", content = @Content(schema = @Schema(implementation = MUCRoomMessageEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public MUCRoomMessageEntities getMUCRoomHistory(
- @Parameter(description = "The name of the chat room for which to return message history", example = "lobby", required = true) @PathParam("roomName") String roomName,
+ @Parameter(description = "The name of the chat room for which to return message history.", example = "lobby", required = true) @PathParam("roomName") String roomName,
@Parameter(description = "The name of the chat room's MUC service.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName)
throws ServiceException
{
@@ -233,16 +233,16 @@ public MUCRoomMessageEntities getMUCRoomHistory(
@Operation( summary = "Invite user or group",
description = "Invites a user or group to join a specific multi-user chat room.",
responses = {
- @ApiResponse(responseCode = "200", description = "Invitation sent"),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "Invitation sent."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to invite a user to this room.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response inviteUserOrGroupToMUCRoom(
- @Parameter(description = "The name of the chat room in which to invite a user or group", example = "lobby", required = true) @PathParam("roomName") String roomName,
- @Parameter(description = "The JID of the entity to invite into the room", example = "john@example.org", required = true) @PathParam("jid") String jid,
+ @Parameter(description = "The name of the chat room to which to invite a user or group.", example = "lobby", required = true) @PathParam("roomName") String roomName,
+ @Parameter(description = "The JID of the entity to invite into the room.", example = "john@example.org", required = true) @PathParam("jid") String jid,
@Parameter(description = "The name of the chat room's MUC service.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@RequestBody(description = "The invitation message to send and whom to send it to.", required = true) MUCInvitationEntity mucInvitationEntity)
throws ServiceException
@@ -262,15 +262,15 @@ public Response inviteUserOrGroupToMUCRoom(
@Operation( summary = "Invite a collection of users and/or groups",
description = "Invites a collection of users and/or groups to join a specific multi-user chat room.",
responses = {
- @ApiResponse(responseCode = "200", description = "Invitation sent"),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "Invitation sent."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Not allowed to invite a user or group to this room.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "The chat room (or its service) can not be found or is not accessible.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response inviteUsersAndOrGroupsToMUCRoom(
- @Parameter(description = "The name of the chat room in which to invite a user or group", example = "lobby", required = true) @PathParam("roomName") String roomName,
+ @Parameter(description = "The name of the chat room to which to invite users and/or groups.", example = "lobby", required = true) @PathParam("roomName") String roomName,
@Parameter(description = "The name of the chat room's MUC service.", example = "conference", required = false) @DefaultValue("conference") @QueryParam("servicename") String serviceName,
@RequestBody(description = "The invitation message to send and whom to send it to.", required = true) MUCInvitationsEntity mucInvitationsEntity)
throws ServiceException
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCServiceService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCServiceService.java
index c01ca0965..0a9f4888a 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCServiceService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/MUCServiceService.java
@@ -34,15 +34,15 @@
import javax.ws.rs.core.Response.Status;
@Path("restapi/v1/chatservices")
-@Tag(name = "Chat service", description = "Managing Multi-User chat services.")
+@Tag(name = "Chat service", description = "Managing multi-user chat services.")
public class MUCServiceService {
@GET
@Operation( summary = "Get chat services",
description = "Get a list of all multi-user chat services.",
responses = {
- @ApiResponse(responseCode = "200", description = "All chat services", content = @Content(schema = @Schema(implementation = MUCServiceEntities.class))),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "200", description = "All chat services.", content = @Content(schema = @Schema(implementation = MUCServiceEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@@ -52,11 +52,11 @@ public MUCServiceEntities getMUCServices()
}
@POST
- @Operation( summary = "Create new multi-user chat service",
+ @Operation( summary = "Create chat service",
description = "Create a new multi-user chat service.",
responses = {
@ApiResponse(responseCode = "201", description = "Service created."),
- @ApiResponse(responseCode = "401", description = "Web service authentication failed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
@ApiResponse(responseCode = "403", description = "Service creation is not permitted.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "409", description = "Service already exists, or another conflict occurred while creating the service.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/MessageService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/MessageService.java
index 831dcd556..e7cad477a 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/MessageService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/MessageService.java
@@ -17,11 +17,14 @@
package org.jivesoftware.openfire.plugin.rest.service;
import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.jivesoftware.openfire.plugin.rest.controller.MessageController;
import org.jivesoftware.openfire.plugin.rest.entity.MessageEntity;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -49,6 +52,8 @@ public void init() {
responses = {
@ApiResponse(responseCode = "201", description = "Message is sent."),
@ApiResponse(responseCode = "400", description = "The message content is empty or missing."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public Response sendBroadcastMessage(@RequestBody(description = "The message that is to be broadcast.", required = true) MessageEntity messageEntity)
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/MsgArchiveService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/MsgArchiveService.java
index 79562be43..e8bf61dc4 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/MsgArchiveService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/MsgArchiveService.java
@@ -24,6 +24,7 @@
import io.swagger.v3.oas.annotations.tags.Tag;
import org.jivesoftware.openfire.plugin.rest.controller.MsgArchiveController;
import org.jivesoftware.openfire.plugin.rest.entity.MsgArchiveEntity;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import org.xmpp.packet.JID;
@@ -49,7 +50,9 @@ public void init() {
@Operation( summary = "Unread message count",
description = "Gets a count of messages that haven't been delivered to the user yet.",
responses = {
- @ApiResponse(responseCode = "200", description = "A message count", content = @Content(schema = @Schema(implementation = MsgArchiveEntity.class)))
+ @ApiResponse(responseCode = "200", description = "A message count.", content = @Content(schema = @Schema(implementation = MsgArchiveEntity.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public MsgArchiveEntity getUnReadMessagesCount(@Parameter(description = "The (bare) JID of the user for which the unread message count needs to be fetched.", example = "john@example.org", required = true) @PathParam("jid") String jidStr)
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/SecurityAuditLogService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/SecurityAuditLogService.java
index d77a38a61..87c9d014a 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/SecurityAuditLogService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/SecurityAuditLogService.java
@@ -24,6 +24,7 @@
import io.swagger.v3.oas.annotations.tags.Tag;
import org.jivesoftware.openfire.plugin.rest.controller.SecurityAuditLogController;
import org.jivesoftware.openfire.plugin.rest.entity.SecurityAuditLogs;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -46,7 +47,9 @@ public void init() {
description = "Retrieve entries from the security audit log.",
responses = {
@ApiResponse(responseCode = "200", description = "The requested log entries.", content = @Content(schema = @Schema(implementation = SecurityAuditLogs.class))),
- @ApiResponse(responseCode = "403", description = "The audit log is not readable (configured to be write-only).")
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "403", description = "The audit log is not readable (configured to be write-only).", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public SecurityAuditLogs getSecurityAuditLogs(
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/SessionService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/SessionService.java
index 33a3fcb2b..2f704d5a4 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/SessionService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/SessionService.java
@@ -24,6 +24,7 @@
import io.swagger.v3.oas.annotations.tags.Tag;
import org.jivesoftware.openfire.plugin.rest.controller.SessionController;
import org.jivesoftware.openfire.plugin.rest.entity.SessionEntities;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -47,6 +48,8 @@ public void init() {
description = "Retrieve all live client sessions.",
responses = {
@ApiResponse(responseCode = "200", description = "The client sessions currently active in Openfire.", content = @Content(schema = @Schema(implementation = SessionEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public SessionEntities getAllSessions() throws ServiceException {
@@ -59,6 +62,8 @@ public SessionEntities getAllSessions() throws ServiceException {
description = "Retrieve all live client sessions for a particular user.",
responses = {
@ApiResponse(responseCode = "200", description = "The client sessions for one particular user that are currently active in Openfire.", content = @Content(schema = @Schema(implementation = SessionEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public SessionEntities getUserSessions(
@@ -73,6 +78,8 @@ public SessionEntities getUserSessions(
description = "Close/disconnect all live client sessions for a particular user.",
responses = {
@ApiResponse(responseCode = "200", description = "The client sessions for one particular user have been closed."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Path("/{username}")
public Response kickSession(
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/StatisticsService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/StatisticsService.java
index a00d93bb0..304256828 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/StatisticsService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/StatisticsService.java
@@ -23,6 +23,7 @@
import io.swagger.v3.oas.annotations.tags.Tag;
import org.jivesoftware.openfire.plugin.rest.controller.StatisticsController;
import org.jivesoftware.openfire.plugin.rest.entity.SessionsCount;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -45,9 +46,11 @@ public void init() {
@GET
@Path("/sessions")
@Operation( summary = "Get client session counts",
- description = "Retrieve statistics on the amount of client sessions.",
+ description = "Retrieve statistics on the number of client sessions.",
responses = {
@ApiResponse(responseCode = "200", description = "The requested statistics.", content = @Content(schema = @Schema(implementation = SessionsCount.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public SessionsCount getCCS() throws ServiceException {
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/SystemService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/SystemService.java
index 09424977c..184c45ad4 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/SystemService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/SystemService.java
@@ -26,6 +26,7 @@
import org.jivesoftware.openfire.plugin.rest.controller.SystemController;
import org.jivesoftware.openfire.plugin.rest.entity.SystemProperties;
import org.jivesoftware.openfire.plugin.rest.entity.SystemProperty;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import org.jivesoftware.openfire.spi.ConnectionType;
@@ -34,7 +35,7 @@
import javax.ws.rs.core.Response;
@Path("restapi/v1/system")
-@Tag(name = "System", description = "Managing Openfire system configuration")
+@Tag(name = "System", description = "Managing Openfire system configuration.")
public class SystemService {
@GET
@@ -43,6 +44,8 @@ public class SystemService {
description = "Get all Openfire system properties.",
responses = {
@ApiResponse(responseCode = "200", description = "The system properties.", content = @Content(schema = @Schema(implementation = SystemProperties.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public SystemProperties getSystemProperties() {
@@ -55,8 +58,10 @@ public SystemProperties getSystemProperties() {
description = "Get a specific Openfire system property.",
responses = {
@ApiResponse(responseCode = "200", description = "The requested system property.", content = @Content(schema = @Schema(implementation = SystemProperty.class))),
- @ApiResponse(responseCode = "403", description = "Reading this system property is prohibited."),
- @ApiResponse(responseCode = "404", description = "The system property could not be found.")
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "403", description = "Reading this system property is prohibited.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "404", description = "The system property could not be found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public SystemProperty getSystemProperty(
@@ -72,9 +77,11 @@ public SystemProperty getSystemProperty(
description = "Create a new Openfire system property. Will overwrite a pre-existing system property that uses the same name.",
responses = {
@ApiResponse(responseCode = "201", description = "The system property is created."),
- @ApiResponse(responseCode = "400", description = "No system property was provided, the system property has no value, or its name is not valid. The name must consist of one or more dot-separated parts, each consisting of ASCII letters, digits, underscores, apostrophes and hyphens."),
- @ApiResponse(responseCode = "403", description = "Prohibited to create this system property."),
- @ApiResponse(responseCode = "409", description = "The name of the system property differs only in case from the name of an existing system property."),
+ @ApiResponse(responseCode = "400", description = "No system property was provided, the system property has no value, or its name is not valid. The name must consist of one or more dot-separated parts, each consisting of ASCII letters, digits, underscores, apostrophes and hyphens.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "403", description = "Prohibited to create this system property.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "409", description = "The name of the system property differs only in case from the name of an existing system property.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response createSystemProperty(
@@ -91,15 +98,17 @@ public Response createSystemProperty(
description = "Updates an existing Openfire system property.",
responses = {
@ApiResponse(responseCode = "200", description = "The system property is updated."),
- @ApiResponse(responseCode = "400", description = "No system property was provided, the system property has no value, or it does not match the name in the URL."),
- @ApiResponse(responseCode = "403", description = "Prohibited to update this system property."),
- @ApiResponse(responseCode = "404", description = "The system property could not be found."),
- @ApiResponse(responseCode = "409", description = "The name of the system property differs only in case from the name of another existing system property.")
+ @ApiResponse(responseCode = "400", description = "No system property was provided, the system property has no value, or it does not match the name in the URL.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "403", description = "Prohibited to update this system property.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "404", description = "The system property could not be found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "409", description = "The name of the system property differs only in case from the name of another existing system property.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response updateSystemProperty(
@Parameter(description = "The name of the system property to update.", example = "foo.bar.xyz", required = true) @PathParam("propertyKey") String propertyKey,
- @RequestBody(description = "The new system property definition that replaced an existing definition.", required = true) SystemProperty systemProperty)
+ @RequestBody(description = "The new system property definition that replaces an existing definition.", required = true) SystemProperty systemProperty)
throws ServiceException
{
SystemController.getInstance().updateSystemProperty(propertyKey, systemProperty);
@@ -112,10 +121,12 @@ public Response updateSystemProperty(
description = "Removes an existing Openfire system property, together with all of its child properties (properties of which the name starts with the name of this property, followed by a dot).",
responses = {
@ApiResponse(responseCode = "200", description = "The system property and its child properties are deleted."),
- @ApiResponse(responseCode = "400", description = "The name of the system property is not valid. It must consist of one or more dot-separated parts, each consisting of ASCII letters, digits, underscores, apostrophes and hyphens."),
- @ApiResponse(responseCode = "403", description = "Prohibited to delete this system property, or one of its child properties."),
- @ApiResponse(responseCode = "404", description = "The system property could not be found."),
- @ApiResponse(responseCode = "409", description = "Deleting this system property could also delete unintended properties (other than this property and its child properties). This can happen, for example, when its name contains an underscore, which can match any character.")
+ @ApiResponse(responseCode = "400", description = "The name of the system property is not valid. It must consist of one or more dot-separated parts, each consisting of ASCII letters, digits, underscores, apostrophes and hyphens.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "403", description = "Prohibited to delete this system property, or one of its child properties.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "404", description = "The system property could not be found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "409", description = "Deleting this system property could also delete unintended properties (other than this property and its child properties). This can happen, for example, when its name contains an underscore, which can match any character.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response deleteSystemProperty(
@Parameter(description = "The name of the system property to delete.", example = "foo.bar.xyz", required = true) @PathParam("propertyKey") String propertyKey)
@@ -146,7 +157,7 @@ public Response liveness() {
@GET
@Path("/liveness/deadlock")
- @Operation( summary = "Perform 'deadlock' liveness check.",
+ @Operation( summary = "Perform 'deadlock' liveness check",
description = "Detects if Openfire has reached a state that it cannot recover from because of a deadlock.",
responses = {
@ApiResponse(responseCode = "200", description = "The system is live."),
@@ -162,7 +173,7 @@ public Response livenessDeadlock() {
@GET
@Path("/liveness/properties")
- @Operation( summary = "Perform 'properties' liveness check.",
+ @Operation( summary = "Perform 'properties' liveness check",
description = "Detects if Openfire has reached a state that it cannot recover from because a system property change requires a restart to take effect.",
responses = {
@ApiResponse(responseCode = "200", description = "The system is live."),
@@ -259,7 +270,7 @@ public Response readinessPlugins() {
@ApiResponse(responseCode = "503", description = "Openfire currently does not accept (all) connections.")
})
public Response readinessConnections(
- @Parameter(description = "Optional. Use to limit the check to one particular connection type. One of: SOCKET_S2S, SOCKET_C2S, BOSH_C2S, WEBADMIN, COMPONENT, CONNECTION_MANAGER", example = "SOCKET_C2S", required = false) @QueryParam("connectionType") String connectionType,
+ @Parameter(description = "Optional. Use to limit the check to one particular connection type. One of: SOCKET_S2S, SOCKET_C2S, BOSH_C2S, WEBADMIN, COMPONENT, CONNECTION_MANAGER.", example = "SOCKET_C2S", required = false) @QueryParam("connectionType") String connectionType,
@Parameter(description = "Check the encrypted (true) or unencrypted (false) variant of the connection type. Only used in combination with 'connectionType', as without it, all types and both encrypted and unencrypted are checked.", required = false) @QueryParam("encrypted") Boolean encrypted
) {
if (connectionType != null && !connectionType.isEmpty()) {
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserGroupService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserGroupService.java
index d62e66b74..b52dae5ea 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserGroupService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserGroupService.java
@@ -25,6 +25,7 @@
import io.swagger.v3.oas.annotations.tags.Tag;
import org.jivesoftware.openfire.plugin.rest.controller.UserServiceController;
import org.jivesoftware.openfire.plugin.rest.entity.UserGroupsEntity;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -48,10 +49,13 @@ public void init() {
description = "Retrieve names of all groups that a particular user is in.",
responses = {
@ApiResponse(responseCode = "200", description = "The names of the groups that the user is in.", content = @Content(schema = @Schema(implementation = UserGroupsEntity.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with that username was found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public UserGroupsEntity getUserGroups(
- @Parameter(description = "The username for user for which to return group names.", required = true) @PathParam("username") String username)
+ @Parameter(description = "The username of the user for which to return group names.", required = true) @PathParam("username") String username)
throws ServiceException
{
return new UserGroupsEntity(plugin.getUserGroups(username));
@@ -62,7 +66,9 @@ public UserGroupsEntity getUserGroups(
description = "Add a particular user to a collection of groups. When a group that is provided does not exist, it will be automatically created if possible.",
responses = {
@ApiResponse(responseCode = "201", description = "The user was added to all groups."),
- @ApiResponse(responseCode = "400", description = "When the username cannot be parsed into a JID.")
+ @ApiResponse(responseCode = "400", description = "The username cannot be parsed into a JID.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addUserToGroups(
@@ -77,10 +83,12 @@ public Response addUserToGroups(
@POST
@Path("/{groupName}")
@Operation( summary = "Add user to group",
- description = "Add a particular user to a particular group. When the group that does not exist, it will be automatically created if possible.",
+ description = "Add a particular user to a particular group. When the group does not exist, it will be automatically created if possible.",
responses = {
- @ApiResponse(responseCode = "201", description = "The user was added to the groups."),
- @ApiResponse(responseCode = "400", description = "When the username cannot be parsed into a JID.")
+ @ApiResponse(responseCode = "201", description = "The user was added to the group."),
+ @ApiResponse(responseCode = "400", description = "The username cannot be parsed into a JID.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response addUserToGroup(
@Parameter(description = "The username of the user that is to be added to a group.", required = true) @PathParam("username") String username,
@@ -97,7 +105,9 @@ public Response addUserToGroup(
description = "Removes a user from a group.",
responses = {
@ApiResponse(responseCode = "200", description = "The user was taken out of the group."),
- @ApiResponse(responseCode = "404", description = "The group could not be found."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "The group could not be found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response deleteUserFromGroup(
@Parameter(description = "The username of the user that is to be removed from a group.", required = true) @PathParam("username") String username,
@@ -112,12 +122,14 @@ public Response deleteUserFromGroup(
@Operation( summary = "Delete user from groups",
description = "Removes a user from a collection of groups.",
responses = {
- @ApiResponse(responseCode = "200", description = "The user was taken out of the group."),
- @ApiResponse(responseCode = "404", description = "One or more groups could not be found."),
+ @ApiResponse(responseCode = "200", description = "The user was taken out of the groups."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "One or more groups could not be found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response deleteUserFromGroups(
- @Parameter(description = "The username of the user that is to be removed from a group.", required = true) @PathParam("username") String username,
+ @Parameter(description = "The username of the user that is to be removed from groups.", required = true) @PathParam("username") String username,
@RequestBody(description = "A collection of names for groups from which the user is to be removed.", required = true) UserGroupsEntity userGroupsEntity)
throws ServiceException
{
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserLockoutService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserLockoutService.java
index a2b1d7b16..615a133f8 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserLockoutService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserLockoutService.java
@@ -18,9 +18,12 @@
import io.swagger.v3.oas.annotations.Operation;
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.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.jivesoftware.openfire.plugin.rest.controller.UserServiceController;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -47,7 +50,9 @@ public void init() {
description = "Lockout / ban the user from the chat server. The user will be kicked if the user is online.",
responses = {
@ApiResponse(responseCode = "201", description = "The user was locked out."),
- @ApiResponse(responseCode = "404", description = "No user of with this username exists.")
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with this username exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response disableUser(
@Parameter(description = "The username of the user that is to be locked out.", required = true) @PathParam("username") String username)
@@ -63,7 +68,9 @@ public Response disableUser(
description = "Removes a previously applied lockout / ban of a user.",
responses = {
@ApiResponse(responseCode = "200", description = "User is unlocked."),
- @ApiResponse(responseCode = "404", description = "No user of with this username exists.")
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with this username exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response enableUser(
@Parameter(description = "The username of the user for which the lockout is to be undone.", required = true) @PathParam("username") String username)
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserRosterService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserRosterService.java
index 68ad31a62..644bf1088 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserRosterService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserRosterService.java
@@ -27,6 +27,7 @@
import org.jivesoftware.openfire.plugin.rest.controller.UserServiceController;
import org.jivesoftware.openfire.plugin.rest.entity.RosterEntities;
import org.jivesoftware.openfire.plugin.rest.entity.RosterItemEntity;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ExceptionType;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import org.jivesoftware.openfire.user.UserAlreadyExistsException;
@@ -56,11 +57,13 @@ public void init() {
@Operation( summary = "Retrieve user roster",
description = "Get a list of all roster entries (buddies / contact list) of a particular user.",
responses = {
- @ApiResponse(responseCode = "200", description = "All roster entries", content = @Content(schema = @Schema(implementation = RosterEntities.class))),
- @ApiResponse(responseCode = "404", description = "No user of with this username exists.")
+ @ApiResponse(responseCode = "200", description = "All roster entries.", content = @Content(schema = @Schema(implementation = RosterEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with this username exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
- public RosterEntities getUserRoster(@Parameter(description = "The username of the user for which the retrieve the roster entries.", required = true) @PathParam("username") String username) throws ServiceException {
+ public RosterEntities getUserRoster(@Parameter(description = "The username of the user for which to retrieve the roster entries.", required = true) @PathParam("username") String username) throws ServiceException {
return plugin.getRosterEntities(username);
}
@@ -69,13 +72,15 @@ public RosterEntities getUserRoster(@Parameter(description = "The username of th
description = "Add a roster entry to the roster (buddies / contact list) of a particular user.",
responses = {
@ApiResponse(responseCode = "201", description = "The entry was added to the roster."),
- @ApiResponse(responseCode = "400", description = "A roster entry cannot be added to a 'shared group' (try removing group names from the roster entry and try again)."),
- @ApiResponse(responseCode = "404", description = "No user of with this username exists."),
- @ApiResponse(responseCode = "409", description = "A roster entry already exists for the provided contact JID.")
+ @ApiResponse(responseCode = "400", description = "A roster entry cannot be added to a 'shared group' (try removing group names from the roster entry and try again).", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with this username exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "409", description = "A roster entry already exists for the provided contact JID.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response createRoster(
- @Parameter(description = "The username of the user for which the add a roster entry.", required = true) @PathParam("username") String username,
+ @Parameter(description = "The username of the user for which to add a roster entry.", required = true) @PathParam("username") String username,
@RequestBody(description = "The definition of the roster entry that is to be added.", required = true) RosterItemEntity rosterItemEntity)
throws ServiceException
{
@@ -99,12 +104,14 @@ public Response createRoster(
@Operation( summary = "Remove roster entry",
description = "Removes one of the roster entries (contacts) of a particular user.",
responses = {
- @ApiResponse(responseCode = "200", description = "Entry removed"),
- @ApiResponse(responseCode = "400", description = "A roster entry cannot be removed from a 'shared group'."),
- @ApiResponse(responseCode = "404", description = "No user of with this username exists, or its roster did not contain this entry.")
+ @ApiResponse(responseCode = "200", description = "The entry was removed from the roster."),
+ @ApiResponse(responseCode = "400", description = "A roster entry cannot be removed from a 'shared group'.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with this username exists, or its roster did not contain this entry.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response deleteRoster(
- @Parameter(description = "The username of the user for which the remove a roster entry.", required = true) @PathParam("username") String username,
+ @Parameter(description = "The username of the user for which to remove a roster entry.", required = true) @PathParam("username") String username,
@Parameter(description = "The JID of the entry/contact to remove.", required = true) @PathParam("rosterJid") String rosterJid)
throws ServiceException
{
@@ -123,13 +130,15 @@ public Response deleteRoster(
description = "Changes a roster entry on the roster (buddies / contact list) of a particular user.",
responses = {
@ApiResponse(responseCode = "200", description = "The roster entry was updated."),
- @ApiResponse(responseCode = "400", description = "A roster entry cannot be added with a 'shared group'."),
- @ApiResponse(responseCode = "404", description = "No user of with this username exists."),
- @ApiResponse(responseCode = "409", description = "A roster entry already exists for the provided contact JID.")
+ @ApiResponse(responseCode = "400", description = "A roster entry cannot be added with a 'shared group'.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with this username exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "409", description = "A roster entry already exists for the provided contact JID.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response updateRoster(
- @Parameter(description = "The username of the user for which the update a roster entry.", required = true) @PathParam("username") String username,
+ @Parameter(description = "The username of the user for which to update a roster entry.", required = true) @PathParam("username") String username,
@Parameter(description = "The JID of the entry/contact to update.", required = true) @PathParam("rosterJid") String rosterJid,
@RequestBody(description = "The updated definition of the roster entry.", required = true) RosterItemEntity rosterItemEntity)
throws ServiceException
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserService.java
index 78946fdad..e573601d2 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserService.java
@@ -26,6 +26,7 @@
import org.jivesoftware.openfire.plugin.rest.controller.UserServiceController;
import org.jivesoftware.openfire.plugin.rest.entity.UserEntities;
import org.jivesoftware.openfire.plugin.rest.entity.UserEntity;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import javax.annotation.PostConstruct;
@@ -49,12 +50,14 @@ public void init() {
description = "Retrieve all users defined in Openfire (with optional filtering).",
responses = {
@ApiResponse(responseCode = "200", description = "A list of Openfire users.", content = @Content(schema = @Schema(implementation = UserEntities.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public UserEntities getUsers(
- @Parameter(description = "Search/Filter by username. This act like the wildcard search %String%", required = false) @QueryParam("search") String userSearch,
+ @Parameter(description = "Search/Filter by username. This acts like the wildcard search %String%.", required = false) @QueryParam("search") String userSearch,
@Parameter(description = "Filter by a user property name.", required = false) @QueryParam("propertyKey") String propertyKey,
- @Parameter(description = "Filter by user property value. Note: This can only be used in combination with a property name parameter", required = false) @QueryParam("propertyValue") String propertyValue)
+ @Parameter(description = "Filter by user property value. Note: This can only be used in combination with a property name parameter.", required = false) @QueryParam("propertyValue") String propertyValue)
throws ServiceException
{
return plugin.getUserEntities(userSearch, propertyKey, propertyValue);
@@ -65,6 +68,10 @@ public UserEntities getUsers(
description = "Add a new user to Openfire.",
responses = {
@ApiResponse(responseCode = "201", description = "The user was created."),
+ @ApiResponse(responseCode = "400", description = "No user definition, username or password was provided.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "409", description = "A user with this username already exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response createUser(
@@ -80,8 +87,10 @@ public Response createUser(
@Operation( summary = "Get user",
description = "Retrieve a user that is defined in Openfire.",
responses = {
- @ApiResponse(responseCode = "200", description = "A list of Openfire users.", content = @Content(schema = @Schema(implementation = UserEntity.class))),
- @ApiResponse(responseCode = "404", description = "No user with that username was found."),
+ @ApiResponse(responseCode = "200", description = "The Openfire user.", content = @Content(schema = @Schema(implementation = UserEntity.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with that username was found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public UserEntity getUser(
@@ -97,11 +106,15 @@ public UserEntity getUser(
description = "Update an existing user in Openfire.",
responses = {
@ApiResponse(responseCode = "200", description = "The user was updated."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with that username was found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "409", description = "The user is to be renamed, but a user with the new username already exists.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response updateUser(
@Parameter(description = "The username of the user to update.", required = true) @PathParam("username") String username,
- @RequestBody(description = "The definition update of the user.", required = true) UserEntity userEntity)
+ @RequestBody(description = "The updated definition of the user.", required = true) UserEntity userEntity)
throws ServiceException
{
plugin.updateUser(username, userEntity);
@@ -114,7 +127,9 @@ public Response updateUser(
description = "Remove an existing user from Openfire.",
responses = {
@ApiResponse(responseCode = "200", description = "The user was removed."),
- @ApiResponse(responseCode = "404", description = "No user with that username was found."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "404", description = "No user with that username was found.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response deleteUser(@Parameter(description = "The username of the user to remove.", required = true) @PathParam("username") String username) throws ServiceException {
plugin.deleteUser(username);
diff --git a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserVCardService.java b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserVCardService.java
index c3ca53926..e8cfa4687 100644
--- a/src/java/org/jivesoftware/openfire/plugin/rest/service/UserVCardService.java
+++ b/src/java/org/jivesoftware/openfire/plugin/rest/service/UserVCardService.java
@@ -28,6 +28,7 @@
import org.jivesoftware.openfire.plugin.rest.controller.UserServiceController;
import org.jivesoftware.openfire.plugin.rest.entity.RosterItemEntity;
import org.jivesoftware.openfire.plugin.rest.entity.UserGroupsEntity;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ErrorResponse;
import org.jivesoftware.openfire.plugin.rest.exceptions.ExceptionType;
import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
import org.jivesoftware.openfire.user.UserAlreadyExistsException;
@@ -39,7 +40,7 @@
import javax.ws.rs.core.Response;
@Path("restapi/v1/users/{username}/vcard")
-@Tag(name = "Users", description = "Managing vCards of Openfire users.")
+@Tag(name = "Users", description = "Managing Openfire users.")
public class UserVCardService
{
private UserServiceController plugin;
@@ -53,12 +54,14 @@ public void init() {
@Operation( summary = "Get user's vCard",
description = "Retrieves the vCard for a particular user.",
responses = {
- @ApiResponse(responseCode = "200", description = "The vCard of the user"),
- @ApiResponse(responseCode = "204", description = "No vCard found.")
+ @ApiResponse(responseCode = "200", description = "The vCard of the user."),
+ @ApiResponse(responseCode = "204", description = "No vCard found."),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Produces({MediaType.APPLICATION_XML})
public String getUserVcard(
- @Parameter(description = "The username for user for which to return the vcard.", required = true) @PathParam("username") String username)
+ @Parameter(description = "The username of the user for which to return the vCard.", required = true) @PathParam("username") String username)
throws ServiceException
{
final Element el = plugin.getUserVCard(username);
@@ -73,12 +76,14 @@ public String getUserVcard(
description = "Creates or changes a vCard of a particular user.",
responses = {
@ApiResponse(responseCode = "200", description = "The vCard was updated/created."),
- @ApiResponse(responseCode = "400", description = "Provided data could not be parsed."),
- @ApiResponse(responseCode = "409", description = "Cannot change vCard, as Openfire is configured to have read-only vCards.")
+ @ApiResponse(responseCode = "400", description = "Provided data could not be parsed.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "409", description = "Cannot change vCard, as Openfire is configured to have read-only vCards.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
@Consumes({MediaType.APPLICATION_XML})
public Response setUserVcard(
- @Parameter(description = "The username of the user for which the update a roster entry.", required = true) @PathParam("username") String username,
+ @Parameter(description = "The username of the user for which to update the vCard.", required = true) @PathParam("username") String username,
@RequestBody(description = "The updated definition of the vCard.", required = true) String vCard)
throws ServiceException
{
@@ -91,10 +96,12 @@ public Response setUserVcard(
description = "Removes a vCard of a particular user.",
responses = {
@ApiResponse(responseCode = "200", description = "The vCard was deleted."),
- @ApiResponse(responseCode = "409", description = "Cannot delete vCard, as Openfire is configured to have read-only vCards.")
+ @ApiResponse(responseCode = "401", description = "Web service authentication failed."),
+ @ApiResponse(responseCode = "409", description = "Cannot delete vCard, as Openfire is configured to have read-only vCards.", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+ @ApiResponse(responseCode = "500", description = "Unexpected, generic error condition.", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response deleteUserVcard(
- @Parameter(description = "The username of the user for which the update a roster entry.", required = true) @PathParam("username") String username)
+ @Parameter(description = "The username of the user for which to delete the vCard.", required = true) @PathParam("username") String username)
throws ServiceException
{
plugin.deleteUserVCard(username);