| name | generating-api-docs |
| description | Create comprehensive API documentation with examples, authentication guides, and SDKs.
Use when creating comprehensive API documentation.
Trigger with phrases like "generate API docs", "create API documentation", or "document the API".
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash(api:docs-*) |
| version | 1.27.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| tags | ["api","authentication","api-docs"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
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
