API Documentation Patterns

Engineering great API documentation — from OpenAPI descriptions to interactive playgrounds, changelog automation, and prose quality checks. API documentation is a product, not an afterthought.

When to Activate

• Building or overhauling API documentation for any team or public audience
• Choosing a documentation platform (Mintlify, Docusaurus, Redoc, Scalar)
• Implementing changelog automation with semantic-release or release-please
• Adding interactive API playground or code examples to existing docs
• Setting up Vale prose linting or broken-link checks in CI
• Auditing OpenAPI spec descriptions, examples, and x-extensions
• Structuring documentation according to Divio (Tutorial / How-to / Reference / Explanation)

For API design conventions (resource naming, status codes, versioning): see skill api-design. For contract-first workflow (spec linting, code generation, breaking-change CI): see skill api-contract.

Docs-as-Code Philosophy