api-docs-writer

# API Docs Writer ## Overview This skill produces production-quality API reference documentation and OpenAPI 3.1 specifications. It covers endpoint reference pages, parameter/field tables, authentication, pagination, rate limits, request/response examples in multiple languages, and complete error tables. Keywords: API documentation, REST reference, OpenAPI, Swagger, endpoint docs, request schema, response schema, error codes, curl example, parameter table, authentication docs. Use it for two distinct deliverables: 1. **Human-readable reference docs** (Markdown) — one page per resource or endpoint. 2. **Machine-readable OpenAPI 3.1 spec** (YAML/JSON) — the single source of truth for tooling, SDK generation, and doc portals. Prefer generating the OpenAPI spec first, then deriving Markdown from it, when both are requested. ## Process Follow these steps in order. 1. **Gather the source of truth.** Identify where the API behavior is defined: route handlers, controllers, framework decorators (Flask/FastAPI/Express/Spring), existing partial specs, Postman collections, or live responses. Never invent fields — read the code or ask. If a detail is unknown, mark it clearly rather than guessing. 2. **Inventory the surface.** For each endpoint capture: HTTP method, path (with `{path_params}`), summary, auth requirement, query/path/header params, request body schema, success responses (per status code), error responses, and idempotency. Use `references/extraction-checklist.md` to av...