Generating API Documentation

Overview

Create comprehensive, interactive API documentation from OpenAPI specifications with runnable code examples, authentication guides, error reference tables, and SDK quick-start tutorials. Generate documentation sites using Redoc, Stoplight Elements, or Swagger UI with custom branding, versioned navigation, and full-text search.

Prerequisites

• OpenAPI 3.0+ specification with descriptions, examples, and complete schema definitions

• Documentation generator: Redoc, Stoplight Elements, Swagger UI, or Docusaurus with OpenAPI plugin

• Code example generator for multiple languages (curl, JavaScript, Python, Go)

• Static site hosting for documentation deployment (GitHub Pages, Netlify, Vercel)

• Custom branding assets (logo, color scheme) for white-labeled documentation

Instructions

• Read the OpenAPI specification using Read and audit documentation completeness: verify all operations have summary , description , parameter descriptions, and at least one example per request/response.

• Enrich the specification with long-form descriptions using Markdown: add getting-started guides, authentication flow explanations, and rate limiting documentation in the info.description or x-documentation extensions.

• Generate interactive documentation using Redoc or Stoplight Elements with "Try It" functionality that allows consumers to execute requests directly from the documentation page.

• Create runnable code examples for every endpoint in curl, JavaScript (fetch/axios), Python (requests/httpx), and Go (net/http), with proper authentication header injection.

• Build an authentication guide covering all supported auth schemes: API key setup, OAuth2 authorization code flow walkthrough, JWT token lifecycle, and credential rotation procedures.

• Add an error reference section that documents every error code, its meaning, common causes, and resolution steps -- organized by HTTP status code with searchable error code index.

• Configure documentation versioning so consumers can switch between API versions (v1, v2) with visual diff highlighting showing changes between versions.

• Set up automated documentation deployment: on OpenAPI spec changes, regenerate the documentation site and deploy to hosting with cache invalidation.

See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.

Output

• ${CLAUDE_SKILL_DIR}/docs/site/

• Generated documentation website (HTML/CSS/JS)

• ${CLAUDE_SKILL_DIR}/docs/guides/authentication.md

• Authentication flow guide with code examples

• ${CLAUDE_SKILL_DIR}/docs/guides/getting-started.md

• Quick-start tutorial for first API call

• ${CLAUDE_SKILL_DIR}/docs/reference/errors.md

• Complete error code reference with resolution steps

• ${CLAUDE_SKILL_DIR}/docs/examples/

• Per-endpoint code examples in multiple languages

• ${CLAUDE_SKILL_DIR}/docs/config/redoc.yaml

• Documentation generator configuration with branding

Error Handling

Error Cause Solution

Missing examples OpenAPI spec lacks example or examples for request/response schemas Generate examples from schema using Faker-based data; flag missing examples in spec linting

Stale documentation Docs deployed from an older spec version than the running API Tie doc deployment to API deployment pipeline; version docs alongside API releases

Broken Try-It requests CORS not configured for documentation domain on the API server Add documentation domain to CORS Access-Control-Allow-Origin ; or use a proxy for Try-It requests

Code example errors Generated code example uses deprecated SDK method or wrong import path Auto-test code examples against a staging API; version examples alongside SDK releases

Search not working Full-text search index not rebuilt after content update Include search index regeneration in documentation build pipeline; verify Algolia/Lunr config

Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.

Examples

Stripe-style API docs: Generate a three-column documentation layout with navigation on the left, description in the center, and code examples on the right, with language switcher for curl/Node/Python/Ruby.

Versioned documentation site: Host v1 and v2 documentation side-by-side with a version switcher dropdown, and a changelog page highlighting breaking changes and migration steps between versions.

Developer portal: Combine API reference docs with getting-started tutorials, use-case guides, webhooks documentation, and SDK installation instructions in a single searchable portal.

See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.

Resources

• Redoc documentation generator: https://redocly.com/redoc

• Stoplight Elements: https://stoplight.io/open-source/elements

• Swagger UI: https://swagger.io/tools/swagger-ui/

• Documentation best practices: Stripe, Twilio, and GitHub API docs as exemplars