openapi-doc-sync

name	openapi-doc-sync
description	Use when generating or updating API documentation that follows the OpenAPI specification — daily sync that adds new endpoints to the catalog, notes key changes, and bumps the version.

OpenAPI Doc Sync (Daily)

Keeps an OpenAPI-spec-following doc set current with the codebase — the codebase is the source of truth, the spec follows it, not the other way around.

Steps

1. Find the API surface in code (routers/controllers/handlers — search for route decorators/registrations) and the existing spec file(s) (openapi.yaml/openapi.json or generated docs directory).

2. Diff reality vs. spec:

   • New endpoints/methods present in code but missing from the spec → add
   • Endpoints in the spec no longer present in code → flag for removal (don't silently delete; an EM/owner should confirm deprecation)
   • Changed request/response shapes (new required fields, changed types, new status codes) → update + log as a "key change"

3. Update the spec following OpenAPI conventions:

   • Correct paths, parameters, requestBody, responses, components/schemas
   • Keep tags aligned with the existing catalog grouping

4. Bump info.version (semver: patch for additive/non-breaking, minor for new endpoints, major for breaking changes) and append to a changelog section:

   ## v<version> — <date>
   - Added: `POST /v2/widgets` (new endpoint)
   - Changed: `GET /users/{id}` now returns `roles[]` (was single `role`)
   - Deprecated: `GET /v1/legacy-search` (superseded by `/v2/search`)
   

5. Show the diff for review — don't merge spec changes silently, especially anything marked "Changed" or "Deprecated" (those affect consumers).

Notes

• Schedule via /schedule for a daily run (e.g. after the nightly build/merge).
• Never invent a field or endpoint — only document what's actually in the code.
• Breaking changes (removed fields, changed types, new required params) are the most important thing to surface clearly — lead with those.