| name | swagger |
| description | This skill should be used when adding or changing a handler's swaggo annotations, or when asked "why did CI fail on swagger docs", "regenerate the API docs", "add Swagger annotations to this endpoint". Documents the annotation → make swag → CI drift-check flow and the constraint on running it automatically. |
Swagger / OpenAPI docs
API docs are generated by swaggo/swag from annotations on handler methods (doc comments directly above the handler function). Docs are served at /swagger/.
Regenerating
make swag
This runs swag init and rewrites api/docs. Only run this when annotations actually changed — it's a repo-wide constraint (AGENTS.md), not just a style preference, and it must never run automatically without being asked.
CI enforces it
ci-api.yml runs make swag then git diff --quiet -- api/docs — if the regenerated docs differ from what's committed, the build fails. If a handler's annotations changed (new endpoint, changed request/response shape, new status code), regenerate and commit api/docs in the same change, or CI will fail on the drift check described in the verify skill.
