# API OpenAPI Validation Runbook

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 `operationId`s 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.
