openapi-sync
Regenerate and verify docs/openapi/openapi.json, the FastAPI schema snapshot behind the docs site's API reference. Use after changing backend routes, parameters, request or response models, tags or en
SKILL.md.claude/skills/openapi-sync/SKILL.md
GitHubopenapi-sync
The docs site renders /docs/referencia/api from docs/openapi/openapi.json
with fumadocs-openapi; no MDX is generated or committed. The snapshot is
exported by backend/scripts/export_openapi.py, which imports the app without
starting services. CI runs the exporter with --check in the backend job.
Steps
- Regenerate from the Git root:
Without Docker, fromjust backend openapibackend/:uv run --locked python scripts/export_openapi.py > ../docs/openapi/openapi.json. - Review
git diff docs/openapi/openapi.json. Every hunk must come from the intended contract change; an unrelated hunk means another change is already stale or a dependency changed schema output, so report it instead of committing it silently. - Verify:
just backend openapi-check # or: uv run --locked python scripts/export_openapi.py --check ../docs/openapi/openapi.json just docs build # generated pages compile and prerender - Commit the snapshot with the backend change that caused it, and report the commands and results.
Output
Report the operations added, removed or changed (method and path), the check results and any unrelated drift found.
Gotchas
- Never edit
openapi.jsonby hand; improvesummary,description, docstrings or Pydantic models in the backend and regenerate. - Page URLs derive from method and path
(
/docs/referencia/api/<tag>/<method>-<path>), so renaming a route or its tag changes the URL; update links indocs/content/docsthat point to it. - The exporter de-duplicates tags repeated by
APIRouter(tags=...)plusinclude_router(tags=...)and adds the local server for the playground; do not "fix" those differences against/api/py/openapi.json. - Business rules the schema cannot express (permissions, side effects) belong
in
docs/content/docs/referencia/pages such asmiembros-e-invitaciones.md. openapi-checkneeds Docker; a Docker error is not a stale snapshot. Use theuvvariant when Docker is unavailable.