Add Swagger annotations to document endpoints (WIP)

Work-in-progress (this will be force-pushed).

By adding certain annotations, the documentation as generated by Swagger becomes enriched.

src/java/org/jivesoftware/openfire/plugin/rest/service/GroupService.java

@@ -1,22 +1,24 @@
 package org.jivesoftware.openfire.plugin.rest.service;
 
 import javax.annotation.PostConstruct;
-import javax.ws.rs.DELETE;
-import javax.ws.rs.GET;
-import javax.ws.rs.POST;
-import javax.ws.rs.PUT;
-import javax.ws.rs.Path;
-import javax.ws.rs.PathParam;
-import javax.ws.rs.Produces;
+import javax.ws.rs.*;
 import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 
+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.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.GroupController;
 import org.jivesoftware.openfire.plugin.rest.entity.GroupEntities;
 import org.jivesoftware.openfire.plugin.rest.entity.GroupEntity;
 import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
 
 @Path("restapi/v1/groups")
+@Tag(name="User Group", description = "Managing Openfire user groupings.")
 public class GroupService {
 
     private GroupController groupController;
@@ -27,34 +29,78 @@ public void init() {
     }
 
     @GET
+    @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)))
+                })
     @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
-    public GroupEntities getGroups() throws ServiceException {
+    public GroupEntities getGroups() throws ServiceException
+    {
         return new GroupEntities(groupController.getGroups());
     }
 
     @POST
-    public Response createGroup(GroupEntity groupEntity) throws ServiceException {
+    @Operation( summary = "Create group",
+        description = "Create a new user group.",
+        responses = {
+            @ApiResponse(responseCode = "201", description = "Group created."),
+            @ApiResponse(responseCode = "400", description = "Group or group name missing."),
+            @ApiResponse(responseCode = "409", description = "Group already exists.")
+        })
+    @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
+    public Response createGroup(
+            @RequestBody(description = "The group that needs to be created.", required = true) GroupEntity groupEntity)
+        throws ServiceException
+    {
         groupController.createGroup(groupEntity);
         return Response.status(Response.Status.CREATED).build();
     }
-    
+
     @GET
     @Path("/{groupName}")
+    @Operation( summary = "Get group",
+        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.")
+        })
     @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
-    public GroupEntity getGroup(@PathParam("groupName") String groupName) throws ServiceException {
+    public GroupEntity getGroup(@Parameter(description = "The name of the group that needs to be fetched.", example = "Colleagues", required = true) @PathParam("groupName") String groupName)
+        throws ServiceException
+    {
         return groupController.getGroup(groupName);
     }
-    
+
     @PUT
     @Path("/{groupName}")
-    public Response updateGroup(@PathParam("groupName") String groupName, GroupEntity groupEntity) throws ServiceException {
+    @Operation( summary = "Update group",
+        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."),
+            @ApiResponse(responseCode = "404", description = "Group with this name not found."),
+        })
+    @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,
+                                @RequestBody(description = "The new group definition that needs to overwrite the old definition.", required = true) GroupEntity groupEntity )
+        throws ServiceException
+    {
         groupController.updateGroup(groupName, groupEntity);
         return Response.status(Response.Status.OK).build();
     }
 
     @DELETE
     @Path("/{groupName}")
-    public Response deleteGroup(@PathParam("groupName") String groupName) throws ServiceException {
+    @Operation( summary = "Delete group",
+        description = "Removes an existing user group.",
+        responses = {
+            @ApiResponse(responseCode = "200", description = "Group deleted."),
+            @ApiResponse(responseCode = "400", description = "Group not found.")
+        })
+    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
+    {
         groupController.deleteGroup(groupName);
         return Response.status(Response.Status.OK).build();
     }

src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomAdminsService.java

@@ -1,50 +1,86 @@
 package org.jivesoftware.openfire.plugin.rest.service;
 
-import javax.ws.rs.DELETE;
-import javax.ws.rs.DefaultValue;
-import javax.ws.rs.POST;
-import javax.ws.rs.Path;
-import javax.ws.rs.PathParam;
-import javax.ws.rs.QueryParam;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.jivesoftware.openfire.plugin.rest.controller.MUCRoomController;
+import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
+
+import javax.ws.rs.*;
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.Response.Status;
 
-import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
-import org.jivesoftware.openfire.plugin.rest.controller.MUCRoomController;
-
 @Path("restapi/v1/chatrooms/{roomName}/admins")
+@Tag(name = "Chat room", description = "Managing Multi-User chat rooms.")
 public class MUCRoomAdminsService {
 
     @POST
     @Path("/{jid}")
-    public Response addMUCRoomAdmin(@DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("jid") String jid, @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Add room admin",
+        description = "Adds an administrator to a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "201", description = "Administrator added to the room.")
+        })
+    public Response addMUCRoomAdmin(
+            @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 added as an admin.", example = "[email protected]", required = true) @PathParam("jid") String jid,
+            @Parameter(description = "The name of the MUC room to which an administrator is to be added.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
         MUCRoomController.getInstance().addAdmin(serviceName, roomName, jid);
         return Response.status(Status.CREATED).build();
     }
 
     @POST
     @Path("/group/{groupname}")
-    public Response addMUCRoomAdminGroup(@DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("groupname") String groupname, @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Add room admins",
+        description = "Adds all members of an Openfire user group as administrator to a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "201", description = "Administrators added to the room.")
+        })
+    public Response addMUCRoomAdminGroup(
+            @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 administrators of the room.", example = "Operators", required = true) @PathParam("groupname") String groupname,
+            @Parameter(description = "The name of the MUC room to which administrators are to be added.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
         MUCRoomController.getInstance().addAdmin(serviceName, roomName, groupname);
         return Response.status(Status.CREATED).build();
     }
 
     @DELETE
     @Path("/{jid}")
-    public Response deleteMUCRoomAdmin(@PathParam("jid") String jid,
-            @DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Remove room admin",
+        description = "Removes a user as an administrator of a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "200", description = "Administrator removed from the room.")
+        })
+    public Response deleteMUCRoomAdmin(
+            @Parameter(description = "The (bare) JID of the entity that is to be removed as an administrators of the room.", example = "[email protected]", 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 name of the MUC room from which an administrator is to be removed.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
+        // FIXME: check if this removes _all_ affiliations, which probably would be more than we're bargaining for.
         MUCRoomController.getInstance().deleteAffiliation(serviceName, roomName, jid);
         return Response.status(Status.OK).build();
     }
 
     @DELETE
     @Path("/group/{groupname}")
-    public Response deleteMUCRoomAdminGroup(@PathParam("groupname") String groupname,
-            @DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Remove room admins",
+        description = "Removes all members of an Openfire user group as administrator of a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "200", description = "Administrators removed from the room.")
+        })
+    public Response deleteMUCRoomAdminGroup(
+        @Parameter(description = "The name of the user group from which all members will be removed as administrators of the room.", 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 name of the MUC room to which administrators are to be removed.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
+        // FIXME: check if this removes _all_ affiliations, which probably would be more than we're bargaining for.
         MUCRoomController.getInstance().deleteAffiliation(serviceName, roomName, groupname);
         return Response.status(Status.OK).build();
     }

src/java/org/jivesoftware/openfire/plugin/rest/service/MUCRoomMembersService.java

@@ -9,42 +9,83 @@
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.Response.Status;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.jivesoftware.openfire.plugin.rest.exceptions.ServiceException;
 import org.jivesoftware.openfire.plugin.rest.controller.MUCRoomController;
 
 @Path("restapi/v1/chatrooms/{roomName}/members")
+@Tag(name = "Chat room", description = "Managing Multi-User chat rooms.")
 public class MUCRoomMembersService {
 
     @POST
     @Path("/{jid}")
-    public Response addMUCRoomMember(@DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("jid") String jid, @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Add room member",
+        description = "Registers a JID as a member of a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "201", description = "Member added to the room.")
+        })
+    public Response addMUCRoomMember(
+            @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 a registered member.", example = "[email protected]", required = true) @PathParam("jid") String jid,
+            @Parameter(description = "The name of the MUC room to which a member is to be added.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
         MUCRoomController.getInstance().addMember(serviceName, roomName, jid);
         return Response.status(Status.CREATED).build();
     }
 
     @POST
     @Path("/group/{groupname}")
-    public Response addMUCRoomMemberGroup(@DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("groupname") String groupname, @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Add room members",
+        description = "Adds all members of an Openfire user group as registered members of a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "201", description = "Members added to the room.")
+        })
+    public Response addMUCRoomMemberGroup(
+            @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 registered members of the room.", example = "Operators", required = true) @PathParam("groupname") String groupname,
+            @Parameter(description = "The name of the MUC room to which members are to be added.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
         MUCRoomController.getInstance().addMember(serviceName, roomName, groupname);
         return Response.status(Status.CREATED).build();
     }
 
     @DELETE
     @Path("/{jid}")
-    public Response deleteMUCRoomMember(@PathParam("jid") String jid,
-            @DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Remove room member",
+        description = "Removes a JID as a registered member of a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "200", description = "Member removed from the room.")
+        })
+    public Response deleteMUCRoomMember(
+            @Parameter(description = "The (bare) JID of the entity that is to be removed as a registered member of the room.", example = "[email protected]", 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 name of the MUC room from which a member is to be removed.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
+        // FIXME: check if this removes _all_ affiliations, which probably would be more than we're bargaining for.
         MUCRoomController.getInstance().deleteAffiliation(serviceName, roomName, jid);
         return Response.status(Status.OK).build();
     }
 
     @DELETE
     @Path("/group/{groupname}")
-    public Response deleteMUCRoomMemberGroup(@PathParam("groupname") String groupname,
-            @DefaultValue("conference") @QueryParam("servicename") String serviceName,
-            @PathParam("roomName") String roomName) throws ServiceException {
+    @Operation( summary = "Remove room members",
+        description = "Removes all members of an Openfire user group as registered members of a multi-user chat room.",
+        responses = {
+            @ApiResponse(responseCode = "200", description = "Member removed from the room.")
+        })
+    public Response deleteMUCRoomMemberGroup(
+            @Parameter(description = "The name of the user group from which all members will be removed as registered members of the room.", 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 name of the MUC room to which members are to be removed.", example = "lobby", required = true) @PathParam("roomName") String roomName)
+        throws ServiceException
+    {
+        // FIXME: check if this removes _all_ affiliations, which probably would be more than we're bargaining for.
         MUCRoomController.getInstance().deleteAffiliation(serviceName, roomName, groupname);
         return Response.status(Status.OK).build();
     }