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.

5. Add examples. Provide at least a curl example and one realistic JSON request/response pair per endpoint. Use real-looking values, never foo/bar. Show the exact status code. See references/style-guide.md for example conventions.

6. Document errors. Build a per-endpoint error table AND a global error reference. Each row: HTTP status, machine-readable code, when it occurs, and how to fix. Reuse a consistent error envelope.

7. Document cross-cutting concerns. Authentication, pagination, rate limiting, versioning, idempotency keys, and content types. Document these once in shared sections and link to them.

8. Validate. If you produced an OpenAPI file, run scripts/validate_openapi.py path/to/spec.yaml to catch structural errors before delivering. Fix every reported issue.

9. Self-review against references/extraction-checklist.md and the Common Pitfalls list below.

Endpoint documentation structure

Each endpoint page should contain, in order:

• Title: METHOD /path
• One-line summary + auth badge (e.g. Requires: Bearer token)
• Description (behavior, side effects, when to use)
• Path parameters table