Skip to content

fixes #269: Improve completeness, accuracy and consistency of the OpenAPI documentation #270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Fishbowler merged 1 commit into from
Sep 25, 2026
Merged

fixes #269: Improve completeness, accuracy and consistency of the OpenAPI documentation #270

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ <h1>
<p><b>1.12.1</b> (to be determined)</p>
<ul>
<li>Now requires Openfire 5.1.0 or later</li>
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/269">#269</a>] - Improve completeness, accuracy and consistency of the OpenAPI documentation</li>
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/265">#265</a>] - Ensure cross-database compatibility for unread message count query</li>
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/261">#261</a>] - Remove the deprecated 'userservice' endpoint</li>
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/259">#259</a>] - Prevent system property requests from affecting properties other than the one requested</li>
Expand Down
19 changes: 13 additions & 6 deletions src/java/org/jivesoftware/openfire/plugin/rest/service/ClusteringService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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(){
Expand All @@ -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() {
Expand All @@ -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 {
Expand Down
29 changes: 20 additions & 9 deletions src/java/org/jivesoftware/openfire/plugin/rest/service/GroupService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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
Expand All @@ -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(
Expand All @@ -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)
Expand All @@ -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
{
Expand All @@ -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
Expand Down
Loading
Loading