--- name: api-docs-patterns description: "API documentation best practices — OpenAPI spec (paths, components, examples, x-webhooks), docs-as-code CI/CD, platform selection (Mintlify/Redoc/Scalar), interactive playgrounds, changelog automation with conventional commits." --- # 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 Treat documentation exactly like code: version-controlled in Git, reviewed via pull requests, built and deployed in CI. ``` Repository layout — docs next to code ├── api/ │ └── v1/ │ └── openapi.yaml ← spec is the source of truth ├── docs/ │ ├── guides/ ← tutorials and how-tos │ ├── reference/ ← auto-generated from OpenAPI │ └── changelog/ ← CHANGELOG.md or generated ├── mint.json ← Mintlify config (if using Mintlify) └── .github/ └── workflows/ └── docs.yml ← build + lint + deploy ``` **CI pipeline for docs (every PR):** ```yaml # .github/workflows/docs.yml name: Docs CI on: [push, pull_request] jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Lint OpenAPI spec run: npx @stoplight/spectral-cli lint api/v1/openapi.yaml - name: Check prose (Vale) run: vale docs/ - name: Check broken links run: npx lychee --offline docs/**/*.md - name: Build docs run: npm run docs:build - name: Deploy preview (PR only) if: github.event_name == 'pull_request' run: mintlify deploy --preview ``` **Anti-patterns to avoid:** - Word documents or Confluence pages for API docs — they version poorly, go stale within weeks - Generating the OpenAPI spec from code annotations — annotations drift from behavior - Updating docs manually after code changes — automate staleness detection --- ## OpenAPI Documentation Best Practices A well-documented OpenAPI spec is the foundation of every other documentation artifact. Renderers (Redoc, Scalar, Mintlify) consume your spec directly. ### Descriptions — never leave them empty ```yaml # openapi.yaml paths: /users/{id}/orders: get: summary: List orders for a user description: | Returns a paginated list of orders for the specified user. Orders are sorted by `created_at` descending by default. **Scopes required:** `orders:read` **Rate limit:** 100 requests/minute per API key operationId: listUserOrders tags: [Orders] parameters: - name: id in: path required: true description: The unique user identifier (UUID v4). schema: type: string format: uuid example: "550e8400-e29b-41d4-a716-446655440000" - name: status in: query description: | Filter by order status. Comma-separated list of values: `pending`, `processing`, `shipped`, `delivered`, `cancelled`. schema: type: string example: "pending,processing" ``` ### Examples — one per schema variant ```yaml components: schemas: Order: type: object description: Represents a customer order. properties: id: type: string format: uuid description: Unique order identifier. example: "ord_2xNm0kqHrTwV" status: type: string enum: [pending, processing, shipped, delivered, cancelled] description: Current fulfillment status. example: "shipped" total_cents: type: integer description: Order total in the smallest currency unit (e.g., cents for USD). example: 4999 examples: pending_order: summary: Newly created order value: id: "ord_2xNm0kqHrTwV" status: "pending" total_cents: 4999 shipped_order: summary: Order that has been shipped value: id: "ord_9pLq7rJsKwXm" status: "shipped" total_cents: 12750 ``` ### Tags — group endpoints into logical categories ```yaml tags: - name: Users description: User accounts, profiles, and authentication. - name: Orders description: Order creation, management, and history. - name: Billing description: Subscriptions, invoices, and payment methods. externalDocs: description: Billing integration guide url: https://docs.example.com/guides/billing ``` ### x-Extensions — attach custom metadata ```yaml # Per-operation stability and rate-limit metadata paths: /users: post: x-stability: stable # stable | beta | experimental x-rateLimit: requests: 100 window: "1m" scope: "per-api-key" x-codeSamples: - lang: TypeScript label: SDK source: | const user = await client.users.create({ email, name }); - lang: Python label: SDK source: | user = client.users.create(email=email, name=name) - lang: Go label: SDK source: | user, err := client.Users.Create(ctx, &CreateUserRequest{Email: email, Name: name}) - lang: Shell label: curl source: | curl -X POST https://api.example.com/v1/users \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"email":"alice@example.com","name":"Alice"}' # Webhook definitions (OpenAPI 3.1) webhooks: order.shipped: post: summary: Order shipped event description: | Fired when an order transitions to `shipped` status. Retry policy: 3 attempts with exponential backoff (1s, 4s, 16s). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderShippedEvent' ``` --- ## Documentation Platforms | Platform | Best for | Key trait | |----------|----------|-----------| | **Mintlify** | SaaS / external developers | GitHub PR previews, MDX components, zero infra | | **Docusaurus** | Open-source / complex sites | Algolia search free, blog/changelog, React customization | | **Redoc** | Pure API reference only | Classic 3-panel layout, fast render, embeddable | | **Scalar** | Interactive playground | Modern UI, OAuth PKCE, dark mode, ~200 kB bundle | > For detailed per-platform config examples, see skill `docs-strategy`. Scalar embeds with one `