Add comprehensive REST endpoints Swagger documentation

- Analyzed all 132 REST endpoint classes for Swagger annotations
- Created detailed checklist with sub-items for missing documentation
- Identified 6 fully documented classes and 8 partially documented classes
- Documented missing @operation, @apiresponse, @parameter, @RequestBody annotations
- Provides systematic roadmap for completing Swagger documentation across the API

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: spbolton

CLAUDE.md

@@ -228,21 +228,146 @@ public abstract class MyEntity {
 #### REST Endpoints (JAX-RS Pattern)
 ```java
 @Path("/v1/myresource")
+@Tag(name = "Resource Category", description = "Description of this resource group")
 public class MyResource {
     private final WebResource webResource = new WebResource();
 
+    @Operation(
+        summary = "Get resource by ID",
+        description = "Retrieves a specific resource using its identifier"
+    )
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", 
+                    description = "Resource found successfully",
+                    content = @Content(mediaType = "application/json")),
+        @ApiResponse(responseCode = "404", 
+                    description = "Resource not found",
+                    content = @Content(mediaType = "application/json")),
+        @ApiResponse(responseCode = "401", 
+                    description = "Unauthorized access",
+                    content = @Content(mediaType = "application/json"))
+    })
     @GET @Path("/{id}") @Produces(MediaType.APPLICATION_JSON) @NoCache
-    public Response getById(@Context HttpServletRequest request, @PathParam("id") String id) {
+    public Response getById(@Context HttpServletRequest request,
+                           @Parameter(description = "Resource identifier", required = true)
+                           @PathParam("id") String id) {
         // ALWAYS initialize request context
         InitDataObject initData = webResource.init(request, response, true);
         User user = initData.getUser();
 
         // Business logic
         return Response.ok(new ResponseEntityView<>(result)).build();
     }
+    
+    @Operation(
+        summary = "Create new resource",
+        description = "Creates a new resource with the provided data"
+    )
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "201", 
+                    description = "Resource created successfully",
+                    content = @Content(mediaType = "application/json")),
+        @ApiResponse(responseCode = "400", 
+                    description = "Invalid request data",
+                    content = @Content(mediaType = "application/json")),
+        @ApiResponse(responseCode = "401", 
+                    description = "Unauthorized access",
+                    content = @Content(mediaType = "application/json"))
+    })
+    @POST @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) @NoCache
+    public Response create(@Context HttpServletRequest request,
+                          @RequestBody(description = "Resource data to create", 
+                                     required = true,
+                                     content = @Content(schema = @Schema(implementation = MyResourceForm.class)))
+                          MyResourceForm form) {
+        InitDataObject initData = webResource.init(request, response, true);
+        User user = initData.getUser();
+        
+        // Business logic
+        return Response.status(201).entity(new ResponseEntityView<>(result)).build();
+    }
 }
 ```
 
+#### REST Endpoint Documentation Standards
+
+**REQUIRED Swagger/OpenAPI Annotations:**
+```java
+// Class level - ALWAYS required
+@Tag(name = "Category", description = "Brief description")
+
+// Method level - ALL methods MUST have these
+@Operation(summary = "Brief action", description = "Detailed explanation")
+@ApiResponses(value = {
+    @ApiResponse(responseCode = "200", description = "Success description",
+                content = @Content(mediaType = "application/json")),
+    @ApiResponse(responseCode = "4xx/5xx", description = "Error description",
+                content = @Content(mediaType = "application/json"))
+})
+
+// Parameters - ALL path/query parameters MUST be documented
+@Parameter(description = "Parameter purpose", required = true/false)
+
+// Request bodies - ALL POST/PUT/PATCH with bodies MUST be documented
+@RequestBody(description = "Body purpose", required = true,
+           content = @Content(schema = @Schema(implementation = FormClass.class)))
+```
+
+**Media Type Annotation Rules:**
+```java
+// @Produces - ALWAYS specify at method level (not class level)
+@Produces(MediaType.APPLICATION_JSON)                    // Single type
+@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})  // Multiple types
+
+// @Consumes - ONLY on endpoints that accept request bodies
+@GET                                    // NO @Consumes (no body)
+@POST @Consumes(MediaType.APPLICATION_JSON)            // YES @Consumes (has body)
+@PUT @Consumes(MediaType.APPLICATION_JSON)             // YES @Consumes (has body)
+@DELETE                                 // Usually NO @Consumes (no body)
+@DELETE @Consumes(MediaType.APPLICATION_JSON)          // Only if body required
+
+// Special cases - Some GET endpoints accept bodies (non-standard but exists)
+@GET @Consumes(MediaType.APPLICATION_JSON)             // Only if GET accepts body
+```
+
+**Standard Media Types:**
+- Primary: `MediaType.APPLICATION_JSON`
+- Multiple response formats: `{MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML, MediaType.TEXT_PLAIN}`
+- Streaming: `{MediaType.APPLICATION_OCTET_STREAM, MediaType.APPLICATION_JSON}`
+- File uploads: `MediaType.MULTIPART_FORM_DATA`
+
+**Response Status Codes:**
+```java
+// Standard success codes
+return Response.ok(entity).build();                    // 200 OK
+return Response.status(201).entity(entity).build();    // 201 Created
+return Response.noContent().build();                   // 204 No Content
+
+// Standard error responses (document in @ApiResponses)
+// 400 Bad Request - Invalid input
+// 401 Unauthorized - Authentication required  
+// 403 Forbidden - Insufficient permissions
+// 404 Not Found - Resource not found
+// 500 Internal Server Error - Server error
+```
+
+**Deprecation Documentation Standards:**
+```java
+// Class level deprecation (legacy resources)
+@Deprecated
+@Tag(name = "Category", description = "Legacy endpoints (deprecated - use v2 instead)")
+
+// Method level deprecation
+@Operation(
+    summary = "Action name (deprecated)",
+    description = "Method description. This endpoint is deprecated - use v2 CategoryResource instead.",
+    deprecated = true
+)
+
+// Standard deprecation response descriptions
+@ApiResponse(responseCode = "200", description = "Success (deprecated endpoint)")
+```
+
 #### Exception Handling (dotCMS Hierarchy)
 ```java
 // Use specific dotCMS exceptions
@@ -455,9 +580,12 @@ Valid log levels: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `OFF`
 - ✅ Use `Config.getProperty()` and `Logger.info(this, ...)`
 - ✅ Use `APILocator.getXXXAPI()` for services
 - ✅ Use `@Value.Immutable` for data objects
-- ✅ Use JAX-RS `@Path` for REST endpoints
+- ✅ Use JAX-RS `@Path` for REST endpoints with complete Swagger documentation
 - ✅ Use `data-testid` for Angular testing
 - ✅ Use modern Java 21 syntax (Java 11 compatible)
 - ✅ Follow domain-driven package organization for new features
+- ✅ **REST Documentation**: All endpoints MUST have `@Tag`, `@Operation`, `@ApiResponses`, `@Parameter`/`@RequestBody`
+- ✅ **Media Types**: `@Produces` at method level, `@Consumes` only on endpoints with request bodies
 - ❌ Avoid DWR, Struts, portlets, console logging, direct system properties
-- ❌ Avoid Java 21 runtime features in core modules
+- ❌ Avoid Java 21 runtime features in core modules
+- ❌ Avoid `@Consumes` on GET endpoints unless they accept request bodies (non-standard)

dotCMS/src/main/java/com/dotcms/ai/rest/CompletionsResource.java

@@ -22,6 +22,7 @@
 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 javax.ws.rs.Consumes;
 import org.apache.commons.lang3.StringUtils;
 import org.glassfish.jersey.server.JSONP;
 
@@ -61,6 +62,7 @@ public class CompletionsResource {
     @POST
     @JSONP
     @Produces({MediaType.APPLICATION_OCTET_STREAM, MediaType.APPLICATION_JSON})
+    @Consumes(MediaType.APPLICATION_JSON)
     @Operation(
         operationId = "summarizeFromContent",
         summary = "Generate AI completions from content",
@@ -103,6 +105,7 @@ public final Response summarizeFromContent(@Context final HttpServletRequest req
     @POST
     @JSONP
     @Produces({MediaType.APPLICATION_OCTET_STREAM, MediaType.APPLICATION_JSON})
+    @Consumes(MediaType.APPLICATION_JSON)
     @Operation(
         operationId = "rawPrompt",
         summary = "Generate AI completions from raw prompt",

dotCMS/src/main/java/com/dotcms/ai/rest/EmbeddingsResource.java

@@ -21,6 +21,7 @@
 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 javax.ws.rs.Consumes;
 import org.glassfish.jersey.server.JSONP;
 
 import javax.servlet.http.HttpServletRequest;
@@ -62,6 +63,13 @@ public EmbeddingsResource() {
      * @param response the HttpServletResponse object.
      * @return a Response object containing a map with "type" as key and "embeddings" as value.
      */
+    @Operation(
+        summary = "Test AI embeddings service",
+        description = "Returns a test response to verify the AI embeddings service is operational"
+    )
+    @ApiResponse(responseCode = "200", 
+                description = "Test response returned successfully",
+                content = @Content(mediaType = "application/json"))
     @GET
     @JSONP
     @Path("/test")
@@ -80,12 +88,29 @@ public final Response textResource(@Context final HttpServletRequest request,
      * @param embeddingsForm the form data for creating embeddings.
      * @return a Response object containing the result of the embeddings creation.
      */
+    @Operation(
+        summary = "Create AI embeddings",
+        description = "Creates embeddings for content based on the provided form data, processing up to 10,000 content items"
+    )
+    @ApiResponse(responseCode = "200", 
+                description = "Embeddings created successfully",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "401", 
+                description = "Unauthorized - backend user authentication required",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "500", 
+                description = "Internal server error during embeddings creation",
+                content = @Content(mediaType = "application/json"))
     @POST
     @JSONP
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
+    @Consumes(MediaType.APPLICATION_JSON)
     public final Response embed(@Context final HttpServletRequest request,
                                 @Context final HttpServletResponse response,
+                                @RequestBody(description = "Form data containing query, limit, offset, and index configuration for embeddings creation", 
+                                           required = true,
+                                           content = @Content(schema = @Schema(implementation = EmbeddingsForm.class)))
                                 final EmbeddingsForm embeddingsForm) {
 
         // force authentication
@@ -141,12 +166,26 @@ public final Response embed(@Context final HttpServletRequest request,
      * @param json the JSON object containing the data for the embeddings to be deleted.
      * @return a Response object containing the result of the embeddings' deletion.
      */
+    @Operation(
+        summary = "Delete AI embeddings",
+        description = "Deletes embeddings based on provided criteria such as query, identifier, inode, or content type"
+    )
+    @ApiResponse(responseCode = "200", 
+                description = "Embeddings deleted successfully",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "401", 
+                description = "Unauthorized - backend user authentication required",
+                content = @Content(mediaType = "application/json"))
     @DELETE
     @JSONP
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
+    @Consumes(MediaType.APPLICATION_JSON)
     public final Response delete(@Context final HttpServletRequest request,
                                  @Context final HttpServletResponse response,
+                                 @RequestBody(description = "JSON object containing deletion criteria (deleteQuery, indexName, identifier, language, inode, contentType, site)", 
+                                            required = true,
+                                            content = @Content(schema = @Schema(implementation = JSONObject.class)))
                                  final JSONObject json) {
 
         final User user = new WebResource.InitBuilder(request, response).requiredBackendUser(true).init().getUser();
@@ -181,12 +220,29 @@ public final Response delete(@Context final HttpServletRequest request,
      * @param json the JSON object containing the data for the operation.
      * @return a Response object containing the result of the operation.
      */
+    @Operation(
+        summary = "Drop and recreate embeddings tables",
+        description = "Drops and recreates the embeddings database tables. Requires CMS Administrator role."
+    )
+    @ApiResponse(responseCode = "200", 
+                description = "Tables dropped and recreated successfully",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "401", 
+                description = "Unauthorized - backend user authentication required",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "403", 
+                description = "Forbidden - CMS Administrator role required",
+                content = @Content(mediaType = "application/json"))
     @DELETE
     @JSONP
     @Path("/db")
     @Produces(MediaType.APPLICATION_JSON)
+    @Consumes(MediaType.APPLICATION_JSON)
     public final Response dropAndRecreateTables(@Context final HttpServletRequest request,
                                                 @Context final HttpServletResponse response,
+                                                @RequestBody(description = "JSON object (can be empty) for the operation", 
+                                                           required = true,
+                                                           content = @Content(schema = @Schema(implementation = JSONObject.class)))
                                                 final JSONObject json) {
 
         new WebResource.InitBuilder(request, response)
@@ -215,18 +271,35 @@ public final Response dropAndRecreateTables(@Context final HttpServletRequest re
      * @param fieldVar the fieldVar parameter.
      * @return a Response object containing the count of embeddings.
      */
+    @Operation(
+        summary = "Count embeddings (GET)",
+        description = "Counts embeddings based on provided query parameters such as site, content type, index name, etc."
+    )
+    @ApiResponse(responseCode = "200", 
+                description = "Embeddings count retrieved successfully",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "401", 
+                description = "Unauthorized - backend user authentication required",
+                content = @Content(mediaType = "application/json"))
     @GET
     @JSONP
     @Path("/count")
     @Produces(MediaType.APPLICATION_JSON)
     public final Response count(@Context final HttpServletRequest request,
                                 @Context final HttpServletResponse response,
+                                @Parameter(description = "Site identifier")
                                 @QueryParam("site") final String site,
+                                @Parameter(description = "Content type")
                                 @QueryParam("contentType") final String contentType,
+                                @Parameter(description = "Index name")
                                 @QueryParam("indexName") final String indexName,
+                                @Parameter(description = "Language identifier")
                                 @QueryParam("language") final String language,
+                                @Parameter(description = "Content identifier")
                                 @QueryParam("identifier") final String identifier,
+                                @Parameter(description = "Content inode")
                                 @QueryParam("inode") final String inode,
+                                @Parameter(description = "Field variable name")
                                 @QueryParam("fieldVar") final String fieldVar) {
 
         new WebResource.InitBuilder(request, response).requiredBackendUser(true).init().getUser();
@@ -249,12 +322,26 @@ public final Response count(@Context final HttpServletRequest request,
      * @param form the form data for counting embeddings.
      * @return a Response object containing the count of embeddings.
      */
+    @Operation(
+        summary = "Count embeddings (POST)",
+        description = "Counts embeddings based on provided form data containing search criteria"
+    )
+    @ApiResponse(responseCode = "200", 
+                description = "Embeddings count retrieved successfully",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "401", 
+                description = "Unauthorized - backend user authentication required",
+                content = @Content(mediaType = "application/json"))
     @POST
     @JSONP
     @Path("/count")
     @Produces(MediaType.APPLICATION_JSON)
+    @Consumes(MediaType.APPLICATION_JSON)
     public final Response count(@Context final HttpServletRequest request,
                                 @Context final HttpServletResponse response,
+                                @RequestBody(description = "Form data containing count criteria (site, contentType, language, fieldVar, indexName)", 
+                                           required = false,
+                                           content = @Content(schema = @Schema(implementation = CompletionsForm.class)))
                                 final CompletionsForm form) {
 
         new WebResource.InitBuilder(request, response).requiredBackendUser(true).init().getUser();
@@ -273,6 +360,19 @@ public final Response count(@Context final HttpServletRequest request,
      * @param response the HttpServletResponse response.
      * @return a Response object containing the count of embeddings by index.
      */
+    @Operation(
+        summary = "Count embeddings by index",
+        description = "Returns count of embeddings grouped by index name. Requires CMS Administrator role."
+    )
+    @ApiResponse(responseCode = "200", 
+                description = "Index count retrieved successfully",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "401", 
+                description = "Unauthorized - backend user authentication required",
+                content = @Content(mediaType = "application/json"))
+    @ApiResponse(responseCode = "403", 
+                description = "Forbidden - CMS Administrator role required",
+                content = @Content(mediaType = "application/json"))
     @GET
     @JSONP
     @Path("/indexCount")