Use this runbook to keep openapi/openapi.yaml in sync with the codebase and
catch drift early.
What this checks#
- Spec linting:
spectralrules overopenapi/openapi.yaml. - Consistency: Duplicate/missing
operationIds and tags that should map to existingservices/*directories. - CI enforcement:
openapi-validationjob in.github/workflows/quality-gates.ymlruns on pushes/PRs.
How to run locally#
- Install dependencies:
npm ci(from repo root). - Run validation:bash
npm run openapi:validate - Fix any reported issues:
- Add/repair
operationIdfields. - Resolve duplicate IDs.
- If a tag maps to a service (e.g.,
Auth,Content,RAG), ensure the service exists or adjust the tag.
- Add/repair
Interpreting failures#
- Duplicate/missing operationId: Add unique
operationIdto 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-validationjob must stay green before merges.