Eve library

API OpenAPI Validation Runbook

Runbook

Revision 1

On this page

Use this runbook to keep openapi/openapi.yaml in sync with the codebase and catch drift early.

What this checks#

  • Spec linting: spectral rules over openapi/openapi.yaml.
  • Consistency: Duplicate/missing operationIds and tags that should map to existing services/* directories.
  • CI enforcement: openapi-validation job in .github/workflows/quality-gates.yml runs on pushes/PRs.

How to run locally#

  1. Install dependencies: npm ci (from repo root).
  2. Run validation:
    bash
    npm run openapi:validate
    
  3. Fix any reported issues:
    • Add/repair operationId fields.
    • Resolve duplicate IDs.
    • If a tag maps to a service (e.g., Auth, Content, RAG), ensure the service exists or adjust the tag.

Interpreting failures#

  • Duplicate/missing operationId: Add unique operationId to the operation.
  • Tag without service mapping: Either create/rename the service directory or adjust the tag to the correct service name; otherwise leave as a non-service tag.
  • Spectral lint errors: Fix schema/path/response issues reported by spectral.

Updating the spec#

  • Keep tags aligned with service names when the API is owned by a service.
  • Prefer consistent URL shapes (/v1/<area>/<resource>).
  • When adding endpoints, include:
    • operationId, summary, tags, parameters/requestBody, responses (with examples where possible).

Ownership#

  • Spec owners: API Platform / DX team (default reviewers for openapi/*).
  • CI guard: openapi-validation job must stay green before merges.