arabelatso/api-documentation-generator
Generate comprehensive API documentation from repository sources including OpenAPI specs, code comments, docstrings, and existing documentation. Use when documenting APIs, creating API reference guides, or summarizing API functionality from codebases. Extracts endpoint details, request/response schemas, authentication methods, and generates code examples. Triggers when users ask to document APIs, generate API docs, create API reference, or summarize API endpoints from a repository.
npx skills add https://github.com/ArabelaTso/Skills-4-SE --skill api-documentation-generatorAnalyze a repository to extract and generate comprehensive API documentation, including endpoints, request/response schemas, authentication, and usage examples organized in a clear, multi-file structure.
Scan the repository to identify all sources of API information:
Primary sources (in priority order):
.yaml, .yml, .json)/docs, /api, /spec, /openapiopenapi.yaml, swagger.json, api-spec.yaml, etc./docs, /documentation, /api-docsroutes.rb, urls.py, routes.jsDiscovery approach:
# Find OpenAPI specs
find . -name "openapi.*" -o -name "swagger.*" -o -name "*api-spec*"
# Find API route definitions
grep -r "@app.route\|@router\|app.get\|app.post" --include="*.py" --include="*.js"
# Find documentation
find . -path "*/docs/*" -name "*.md" -o -path "*/api/*" -name "*.md"
Based on discovered sources, extract key information:
Parse YAML/JSON to extract:
Look for patterns like:
Python (FastAPI/Flask):
@app.post("/users")
async def create_user(user: UserCreate):
"""
Create a new user.
Args:
user: User creation data
Returns:
Created user object
"""
JavaScript (Express):
/**
* GET /users
* List all users
* @param {number} page - Page number
* @param {number} limit - Items per page
* @returns {Array<User>} List of users
*/
app.get('/users', (req, res) => { ... })
Extract:
Parse markdown files to extract:
Create a multi-file documentation structure organized by resource or API area:
docs/
├── README.md # Overview, authentication, getting started
├── endpoints/
│ ├── users.md # User-related endpoints
│ ├── products.md # Product-related endpoints
│ ├── orders.md # Order-related endpoints
│ └── ...
├── models/
│ └── schemas.md # Data models and schemas
├── errors.md # Error codes and handling
└── examples.md # Complete usage examples
Grouping strategy:
For each file, use the template from assets/api-doc-template.md as a guide.
# API Documentation
## Overview
[Brief description of the API and its purpose]
## Base URL
https://api.example.com/v1
## Authentication
[Describe auth method: Bearer tokens, API keys, OAuth2]
## Quick Start
[Simple example showing how to make first API call]
## Endpoints
- [Users](endpoints/users.md) - User management endpoints
- [Products](endpoints/products.md) - Product catalog endpoints
- [Orders](endpoints/orders.md) - Order processing endpoints
## Resources
- [Data Models](models/schemas.md) - Request/response schemas
- [Errors](errors.md) - Error codes and handling
- [Examples](examples.md) - Complete usage examples
## Rate Limiting
[Rate limit details if applicable]
## Versioning
[API versioning strategy if applicable]
endpoints/users.md)For each endpoint, document:
Endpoint header:
### POST /users
Create a new user account.
Request details:
**Request:**
- **Method:** `POST`
- **Path:** `/users`
- **Headers:**
- `Content-Type: application/json`
- `Authorization: Bearer YOUR_TOKEN`
**Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | User's full name |
| email | string | Yes | User's email address |
| role | string | No | User role (default: user) |
**Example:**
{
"name": "John Doe",
"email": "[email protected]",
"role": "admin"
}
Response details:
**Response:**
- **Status:** `201 Created`
- **Headers:**
- `Location: /users/123`
**Body:**
{
"id": 123,
"name": "John Doe",
"email": "[email protected]",
"role": "admin",
"created_at": "2024-01-15T10:30:00Z"
}
**Error Responses:**
- `400 Bad Request` - Invalid input data
- `409 Conflict` - Email already exists
Code examples:
**Example Request:**
curl -X POST "https://api.example.com/v1/users" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"name": "John Doe",
"email": "[email protected]"
}'
import requests
response = requests.post(
"https://api.example.com/v1/users",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={
"name": "John Doe",
"email": "[email protected]"
}
)
user = response.json()
print(f"Created user: {user['id']}")
models/schemas.md)Document all data structures:
# Data Models
## User
| Field | Type | Description |
|-------|------|-------------|
| id | integer | Unique identifier |
| name | string | User's full name |
| email | string | User's email address |
| role | string | User role (admin, user, guest) |
| created_at | datetime | Account creation timestamp |
| updated_at | datetime | Last update timestamp |
**Example:**
{
"id": 123,
"name": "John Doe",
"email": "[email protected]",
"role": "user",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
errors.md)# Error Handling
All errors follow this format:
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable message"
}
}
## Error Codes
| Status | Code | Description |
|--------|------|-------------|
| 400 | BAD_REQUEST | Invalid request data |
| 401 | UNAUTHORIZED | Missing/invalid auth |
| 403 | FORBIDDEN | Insufficient permissions |
| 404 | NOT_FOUND | Resource not found |
| 409 | CONFLICT | Resource conflict |
| 422 | VALIDATION_ERROR | Validation failed |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests |
| 500 | INTERNAL_ERROR | Server error |
For major use cases, provide complete code examples:
# Examples
## Creating and Managing Users
### 1. Create a User
curl -X POST "https://api.example.com/v1/users" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"name": "John Doe", "email": "[email protected]"}'
import requests
response = requests.post(
"https://api.example.com/v1/users",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={"name": "John Doe", "email": "[email protected]"}
)
user_id = response.json()["id"]
### 2. Retrieve the User
response = requests.get(
f"https://api.example.com/v1/users/{user_id}",
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
user = response.json()
print(f"User: {user['name']} ({user['email']})")
When no OpenAPI spec exists:
When multiple versions exist:
When information is missing:
[To be documented](inferred from code)For GraphQL:
.graphql files or introspectionBefore finalizing documentation:
User request:
> "Generate API documentation for this repository"
Response approach:
openapi.yaml in /docs directoryUser request:
> "Document the API endpoints in this Flask application"
Response approach:
@app.route, @blueprint.route)User request:
> "Summarize the API documentation from all available sources"
Response approach:
Be comprehensive but concise:
Use consistent formatting:
Make it navigable:
Provide context:
Keep it current:
Use the template in assets/api-doc-template.md as a starting point for each documentation file. Adapt the structure based on the specific API being documented.
Take arabelatso/api-documentation-generator from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.