API Documentation Generator
Generate production-ready API documentation from endpoint descriptions. Outputs OpenAPI 3.0, markdown reference docs, and SDK quickstart guides.
About this skill
This AI agent skill empowers developers and teams to automate the creation of high-quality API documentation. By simply providing descriptions of API endpoints, routes, methods, parameters, and responses, the skill generates three crucial outputs: a machine-readable OpenAPI 3.0 YAML specification, human-readable markdown API reference documentation, and practical SDK quickstart guides with code examples. This streamlines the documentation process, ensuring consistency and accuracy across all materials. The skill emphasizes quality, requiring realistic request/response examples, error codes, and notes on pagination, filtering, and versioning. It supports various API styles including REST, GraphQL (schema-first), and gRPC (proto-first). Its utility extends beyond initial documentation, making it an excellent tool for continuous integration/continuous deployment (CI/CD) pipelines to ensure documentation remains up-to-date with every new deploy. Users benefit from reduced manual effort, faster time-to-market for APIs, and improved developer experience for those integrating with their services. The generated OpenAPI spec is ready for tools like Swagger or Postman, while the markdown is perfect for developer portals. The quickstart guides accelerate developer onboarding by providing immediate, copy-paste integration snippets.
Best use case
The primary use case is automating the generation of comprehensive API documentation for development teams. Developers, technical writers, and product managers involved in shipping APIs will benefit most by leveraging this skill to rapidly produce accurate, detailed, and multi-format documentation, freeing them from the tedious manual process of writing and maintaining API docs. This is particularly valuable for projects needing to frequently update API specifications or support multiple client SDKs.
Generate production-ready API documentation from endpoint descriptions. Outputs OpenAPI 3.0, markdown reference docs, and SDK quickstart guides.
A set of three well-structured files: a complete OpenAPI 3.0 YAML specification, a detailed markdown API reference, and a practical markdown SDK quickstart guide, all based on the provided API endpoint descriptions.
Practical example
Example input
Generate API documentation for a user management service. Endpoints include:
- GET /users: retrieves a list of users, supports pagination (limit, offset), returns array of user objects {id, name, email}.
- POST /users: creates a new user, input {name, email}, returns {id, name, email}. Requires authentication.
- GET /users/{id}: retrieves a single user by ID, returns {id, name, email}. Handles 404 if not found.
- PUT /users/{id}: updates a user by ID, input {name, email} (optional), returns updated {id, name, email}.
- DELETE /users/{id}: deletes a user by ID, returns 204 No Content.
Include error responses for 400, 401, 403, 404, 500. Provide realistic examples.Example output
{"openapi.yaml": "openapi: 3.0.0\ninfo:\n title: User Management API\n version: 1.0.0\n...\npaths:\n /users:\n get:\n summary: Get all users\n parameters:\n - in: query\n name: limit\n schema:\n type: integer\n description: Pagination limit\n...\n", "API_Reference.md": "# User Management API Reference\n\n## Authentication\nThis API uses Bearer Token authentication.\n\n## GET /users\nRetrieves a list of all registered users.\n\n### Parameters\n| Name | Type | Description | Required |\n|---|---|---|---|\n| limit | integer | Number of users to return | No |\n...\n\n### Example Request\n```bash\ncurl -X GET \"https://api.example.com/users?limit=10\"\n```\n\n### Example Response (200 OK)\n```json\n[\n { \"id\": \"user123\", \"name\": \"Alice\", \"email\": \"alice@example.com\" }\n]\n```\n...\n", "Quickstart_Guide.md": "# User Management API Quickstart\n\n## Authentication\nAll requests to this API require authentication. Include your API key as a Bearer token in the `Authorization` header.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_API_KEY\" https://api.example.com/users\n```\n\n## Python Example (Get Users)\n```python\nimport requests\n\nheaders = {\"Authorization\": \"Bearer YOUR_API_KEY\"}\nresponse = requests.get(\"https://api.example.com/users\", headers=headers)\nprint(response.json())\n```\n...\n"}When to use this skill
- When launching a new API and needing immediate, comprehensive documentation.
- To automate documentation updates as part of a CI/CD pipeline.
- When onboarding new developers to an existing API and needing quickstart guides.
- To generate machine-readable OpenAPI specs for tools like Swagger or Postman.
When not to use this skill
- When you only need a very simple, informal API description without structured output.
- For documenting non-API-related code or general software features.
- If you prefer entirely manual, highly customized documentation tailored by a human writer for niche cases.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/afrexai-api-docs/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How API Documentation Generator Compares
| Feature / Agent | API Documentation Generator | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | easy | N/A |
Frequently Asked Questions
What does this skill do?
Generate production-ready API documentation from endpoint descriptions. Outputs OpenAPI 3.0, markdown reference docs, and SDK quickstart guides.
How difficult is it to install?
The installation complexity is rated as easy. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
AI Agent for SaaS Idea Validation
Use AI agent skills for SaaS idea validation, market research, customer discovery, competitor analysis, and documenting startup hypotheses.
SKILL.md Source
# API Documentation Generator Generate production-ready API documentation from endpoint descriptions. Outputs OpenAPI 3.0, markdown reference docs, and SDK quickstart guides. ## Usage Describe your API endpoints and this skill generates: 1. **OpenAPI 3.0 spec** — machine-readable, import into Swagger/Postman 2. **Markdown reference** — human-readable endpoint docs with examples 3. **SDK quickstart** — copy-paste integration guide for developers ## Instructions When the user describes API endpoints (routes, methods, parameters, responses): 1. Generate a complete OpenAPI 3.0 YAML specification 2. Create markdown documentation with: - Authentication section - Each endpoint: method, path, description, parameters table, request/response examples - Error codes reference - Rate limiting notes 3. Generate a quickstart guide with curl examples and common language snippets (Python, JavaScript, Go) ### Output Format ```yaml # openapi.yaml — full OpenAPI 3.0 spec ``` ```markdown # API Reference — human-readable docs ``` ```markdown # Quickstart Guide — integration examples ``` ### Quality Standards - Every endpoint must have request AND response examples - Use realistic sample data, not "string" or "example" - Include error responses (400, 401, 403, 404, 500) - Document pagination, filtering, and sorting patterns - Note breaking changes and versioning strategy ## Tips - Paste your route files or controller code for automatic extraction - Works with REST, GraphQL (schema-first), and gRPC (proto-first) - Combine with CI/CD to auto-generate docs on every deploy --- Built by [AfrexAI](https://afrexai-cto.github.io/context-packs/) — AI-powered business tools for teams that ship fast.
Related Skills
Go Production Engineering
You are a Go production engineering expert. Follow this system for every Go project — from architecture decisions through production deployment. Apply phases sequentially for new projects; use individual phases as needed for existing codebases.
Database Engineering Mastery
> Complete database design, optimization, migration, and operations system. From schema design to production monitoring — covers PostgreSQL, MySQL, SQLite, and general SQL patterns.
afrexai-code-reviewer
Enterprise-grade code review agent. Reviews PRs, diffs, or code files for security vulnerabilities, performance issues, error handling gaps, architecture smells, and test coverage. Works with any language, any repo, no dependencies required.
bili-rs
Development skill for bili-rs, a Rust CLI tool for Bilibili (B站). Use when implementing features, fixing bugs, or extending the bilibili-cli-rust codebase. Provides architecture conventions, API endpoints, coding patterns, and project-specific constraints. Triggers on tasks involving adding CLI commands, calling Bilibili APIs, handling authentication, implementing output formatting, or working with the layered cli/commands/client/payloads architecture.
Puppeteer
Automate Chrome and Chromium with Puppeteer for scraping, testing, screenshots, and browser workflows.
pharaoh
Codebase knowledge graph with 23 development workflow skills. Query architecture, dependencies, blast radius, dead code, and test coverage via MCP. Requires GitHub App installation (read-only repo access) and OAuth authentication. Connects to external MCP server at mcp.pharaoh.so.
git-commit-helper
Generate standardized git commit messages following Conventional Commits format. Use this skill when the user asks to commit code, write a commit message, or create a git commit. Enforces team conventions for type prefixes, scope naming, message length, and breaking change documentation.
ask-claude
Delegate a task to Claude Code CLI and immediately report the result back in chat. Supports persistent sessions with full context memory. Safe execution: no data exfiltration, no external calls, file operations confined to workspace. Use when the user asks to run Claude, delegate a coding task, continue a previous Claude session, or any task benefiting from Claude Code's tools (file editing, code analysis, bash, etc.).
bnbchain-mcp
Interact with the BNB Chain Model Context Protocol (MCP) server. Blocks, contracts, tokens, NFTs, wallet, Greenfield, and ERC-8004 agent tools. Use npx @bnb-chain/mcp@latest or read the official skill page.
helius-phantom
Build frontend Solana applications with Phantom Connect SDK and Helius infrastructure. Covers React, React Native, and browser SDK integration, transaction signing via Helius Sender, API key proxying, token gating, NFT minting, crypto payments, real-time updates, and secure frontend architecture.
micropython-skills/sensor
MicroPython sensor reading — DHT11/22, BME280, MPU6050, ADC, ultrasonic HC-SR04, photoresistor, generic I2C sensors.
micropython-skills/network
MicroPython networking — WiFi STA/AP, HTTP requests, MQTT pub/sub, BLE, NTP time sync, WebSocket.