OpenAPI Documentation

This project uses standard JAX-RS and MicroProfile OpenAPI annotations to generate comprehensive API documentation for the Cassandra Sidecar.

Generating Documentation

Build-time Generation

# Generate OpenAPI specifications (JSON and YAML)
./gradlew generateOpenApiSpec

# Generated files:
# - server/build/generated/openapi/openapi.json
# - server/build/generated/openapi/openapi.yaml

Integration with Build

The generated OpenAPI specifications are automatically copied to the application resources during build:

./gradlew build
# OpenAPI specs are packaged in: server/build/resources/main/openapi/

Runtime API Endpoints

The running Sidecar server provides multiple OpenAPI endpoints:

OpenAPI Specifications

• JSON Format: GET http://localhost:9043/spec/openapi.json
• YAML Format: GET http://localhost:9043/spec/openapi.yaml

Interactive Documentation

• Swagger UI: GET http://localhost:9043/openapi.html

Documentation Features

Standard Annotations Approach

The Cassandra Sidecar uses industry-standard annotations for OpenAPI documentation generation:

• JAX-RS Annotations: @GET, @POST, @PUT, @DELETE, @Path - Define HTTP methods and routes
• MicroProfile OpenAPI Annotations: @Operation, @APIResponse, @Schema - Add comprehensive API documentation
• SmallRye OpenAPI Plugin: Gradle plugin that processes annotations to generate OpenAPI specifications

Comprehensive Coverage

• All Endpoints - Health checks, schema operations, snapshots, restore jobs, live migration, CDC, etc.
• HTTP Methods - GET, POST, PUT, DELETE, PATCH operations properly documented
• Path Parameters - Keyspace, table, snapshot names with validation patterns
• Response Schemas - Specific typed responses instead of generic objects

Rich Schema Information

• Response Classes - HealthResponse, SchemaResponse, TableStatsResponse, etc.
• Example Values - JSON examples showing expected response formats
• Error Responses - HTTP status codes with detailed error descriptions
• Content Types - Proper media type specifications (JSON, YAML, HTML, binary)

Organized Structure

• Tags - Endpoints grouped by functionality (Health, Cassandra Operations, Schema, etc.)
• Deprecation Markers - Legacy endpoints clearly marked as deprecated
• Descriptions - Clear summaries and detailed descriptions for each endpoint

Adding Documentation to New Endpoints

When creating new API endpoints, add the appropriate annotations:

@GET
@Path("/api/v1/new-endpoint")
@Operation(summary = "Brief description", 
           description = "Detailed description of what this endpoint does")
@APIResponse(description = "Success response description",
             responseCode = "200",
             content = @Content(mediaType = "application/json",
             schema = @Schema(implementation = MyResponseClass.class)))
public VertxRoute myEndpoint(RouteBuilder.Factory factory, MyHandler handler) {
    return factory.builderForRoute()
                  .handler(handler)
                  .build();
}