openapi-api-specification-implementation

OpenAPI Specification and Implementation

Context

When changes touch API specification files under docs/openapi or implementation files under src, this rule applies.

Core Principles

Specification-Implementation Sync

• Any new endpoint, modification of existing endpoint, or removal must include both the OpenAPI spec change and the matching implementation in src
• If the implementation is deferred, the spec's endpoint description must start with Not implemented yet and the actual handler must return HTTP 501 with a clear JSON message:

{ "error": "Not implemented yet: <feature-name>" }

• Keep examples in sync with actual API behavior

Schema Management

• All request/response bodies and parameters must reference schemas in schemas.yaml
• Reuse existing schemas wherever possible to avoid duplication
• Avoid redefining data structures inline unless absolutely necessary
• Use composition, inheritance, polymorphism (as supported by OpenAPI 3.1.1) to reuse common parts
• When introducing new audit types, update:
  • Audit type enum
  • Audit result schema
  • At least one complete example

Examples

• Add examples to examples.yaml and reference them (don't inline)
• Include at least one request and response example per endpoint
• Examples must validate against the schema and represent realistic, production-like data

Precision & Consistency

• Keep definitions as precise as possible (correct types, constraints, formats, etc.)
• Endpoints under the same tag must follow consistent naming, path structure, response format, etc.

Validation & Documentation Build

• After modifying OpenAPI specs, always run npm run docs:lint to validate the specification
• Before completing implementation, must run npm run docs:build to generate documentation
• Fix any linting errors or build failures before considering the task complete

API Design Patterns

Pagination

• Set strict limits on collection resource items returned
• Support optional limit query parameter with documented defaults, min/max values
• Use cursor-based pagination with cursor query parameter
• Response format: { "cursor": "next-token", "items": [...] }
• Omit cursor property when no more items exist
• Use consistent naming: limit and cursor across all paginated endpoints