loom-api-documentation
Installation
SKILL.md
API Documentation
Overview
Produce API docs developers can actually use: an accurate OpenAPI spec as the source of truth, plus reference/auth/error/versioning guides generated or kept in sync with it. Correctness and drift-prevention matter more than prose.
What every API must document
Auth · base URLs per environment · every endpoint + operation · request/response schemas · all response codes (incl. errors) · rate limits (with headers) · pagination · versioning/deprecation policy.
Spec-first vs code-first (choose deliberately)
| Approach | How | Drift risk | Use when |
|---|---|---|---|
| Spec-first | Hand-write OpenAPI, generate server stubs + clients + mocks | Runtime can diverge from spec unless validated | New APIs, contract negotiated across teams, mock-driven frontend |
| Code-first | Annotate handlers; framework emits spec (FastAPI, springdoc, drf-spectacular, tsoa) | Spec stays close to code, but annotations can lie | Existing codebase, small team, code is the truth |
Either way, enforce the contract in CI (lint + validate examples + breaking-change diff). Docs that aren't tested against the running API are fiction.