Skip to content

Latest commit

 

History

History
99 lines (80 loc) · 4.04 KB

OPENAPI.md

File metadata and controls

99 lines (80 loc) · 4.04 KB

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:

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();
}