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 avoid omissions.

3. Choose the deliverable. If the user wants a spec, scaffold OpenAPI 3.1 (see references/openapi-3.1-reference.md and templates/openapi-skeleton.yaml). If they want a reference page, use templates/endpoint-reference.md.

4. Document each endpoint. Write the summary (imperative, one line), description (behavior, side effects, constraints), parameter tables, request body, and responses. Every parameter row must state: name, in (path/query/header/cookie), type, required, default, constraints, description.