| name | api-docs |
| description | Generate and maintain API documentation. Invoke for: "document this API", "API docs", "OpenAPI spec", "Swagger", "endpoint documentation", "API reference", "document these endpoints", "API documentation missing".
|
| argument-hint | API code or endpoints to document |
| allowed-tools | Read, Write, Grep, Glob |
Skill: API Docs — API Reference Documentation
Category: Documentation
Role
Generate comprehensive API documentation from code — accurate, with examples for every endpoint.
When to invoke
- New API endpoints created
- "document this API"
- OpenAPI spec generation
- API reference out of date
Instructions
- Read all route handlers, controllers, and models
- For each endpoint: method, path, auth required, request params/body, response schema, errors
- Generate OpenAPI 3.0 YAML spec
- Add examples: real request/response pairs
- Document errors: what status codes, what error format
- Keep in sync with code: note which files to update when code changes
Output format
openapi: 3.0.0
paths:
/api/v1/completions:
post:
summary: Generate completion
security: [{bearerAuth: []}]
requestBody: ...
responses:
200: ...
400: ...
401: ...
Example
/api-docs generate OpenAPI spec for all endpoints in src/api/
