API Documentation Skill
Auto-generate comprehensive API documentation with examples, schemas, and interactive tools.
Instructions
You are an API documentation expert. When invoked:
- Generate Documentation:
- Create API reference documentation - Extract info from code comments - Generate from OpenAPI/Swagger specs - Include usage examples - Document authentication methods
- Interactive Documentation:
- Set up Swagger UI - Configure Redoc - Create interactive playgrounds - Add try-it-out features - Include code samples
- Documentation Types:
- API reference guides - Getting started tutorials - Authentication guides - Error handling documentation - Rate limiting policies
- Multi-Format Export:
- HTML documentation - Markdown files - PDF exports - Postman collections - SDK generation
Usage Examples
@api-documentation
@api-documentation --from-openapi
@api-documentation --interactive
@api-documentation --export-postman
@api-documentation --generate-sdkDocumentation Tools
Swagger UI
Setup with Express
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const app = express();
// Load OpenAPI spec
const swaggerDocument = YAML.load('./openapi.yaml');
// Serve Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
customCss: '.swagger-ui .topbar { display: none }',
customSiteTitle: 'My API Documentation',
customfavIcon: '/favicon.ico'
}));
// Serve OpenAPI spec as JSON
app.get('/openapi.json', (req, res) => {
res.json(swaggerDocument);
});
app.listen(3000, () => {
console.log('API docs available at http://localhost:3000/api-docs');
});Custom Swagger Options
const options = {
explorer: true,
swaggerOptions: {
persistAuthorization: true,
displayRequestDuration: true,
filter: true,
syntaxHighlight: {
activate: true,
theme: 'monokai'
}
},
customCss: `
.swagger-ui .topbar { background-color: #2c3e50; }
.swagger-ui .info .title { color: #2c3e50; }
`,
customSiteTitle: 'My API - Documentation',
customfavIcon: '/assets/favicon.ico'
};
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));Redoc
Setup
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const app = express();
// Serve OpenAPI spec
app.get('/openapi.yaml', (req, res) => {
res.sendFile(__dirname + '/openapi.yaml');
});
// Serve Redoc
app.get('/docs', (req, res) => {
res.send(`
<!DOCTYPE html>
<html>
<head>
<title>API Documentation</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<style>
body { margin: 0; padding: 0; }
</style>
</head>
<body>
<redoc spec-url='/openapi.yaml'></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
`);
});
app.listen(3000);Redoc CLI
# Install
npm install -g redoc-cli
# Generate static HTML
redoc-cli bundle openapi.yaml -o docs/index.html
# Serve with live reload
redoc-cli serve openapi.yaml --watch
# Custom options
redoc-cli bundle openapi.yaml \
--output docs/index.html \
--title "My API Documentation" \
--options.theme.colors.primary.main="#2c3e50"Stoplight Elements
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
<title>API Documentation</title>
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css" />
</head>
<body>
<elements-api
apiDescriptionUrl="/openapi.yaml"
router="hash"
layout="sidebar"
/>
</body>
</html>Documentation from Code
JSDoc to OpenAPI
/**
* @openapi
* /api/users:
* get:
* summary: Get all users
* description: Retrieve a paginated list of all users
* tags:
* - Users
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* minimum: 1
* default: 1
* description: Page number
* - in: query
* name: limit
* schema:
* type: integer
* minimum: 1
* maximum: 100
* default: 10
* description: Number of items per page
* responses:
* 200:
* description: Successful response
* content:
* application/json:
* schema:
* type: object
* properties:
* data:
* type: array
* items:
* $ref: '#/components/schemas/User'
* meta:
* $ref: '#/components/schemas/PaginationMeta'
* 401:
* $ref: '#/components/responses/UnauthorizedError'
* security:
* - bearerAuth: []
*/
router.get('/users', async (req, res) => {
// Implementation
});
/**
* @openapi
* components:
* schemas:
* User:
* type: object
* required:
* - id
* - name
* - email
* properties:
* id:
* type: string
* description: User ID
* example: "123"
* name:
* type: string
* description: User's full name
* example: "John Doe"
* email:
* type: string
* format: email
* description: User's email address
* example: "john@example.com"
*/TypeDoc (TypeScript)
/**
* User management API
* @module UserAPI
*/
/**
* Represents a user in the system
* @interface User
*/
interface User {
/** Unique user identifier */
id: string;
/** User's full name */
name: string;
/** User's email address */
email: string;
/** User role */
role: 'user' | 'admin';
}
/**
* Get all users
* @route GET /api/users
* @param {number} page - Page number (default: 1)
* @param {number} limit - Items per page (default: 10)
* @returns {Promise<User[]>} List of users
* @throws {UnauthorizedError} If not authenticated
*/
export async function getUsers(
page: number = 1,
limit: number = 10
): Promise<User[]> {
// Implementation
}
/**
* Create a new user
* @route POST /api/users
* @param {CreateUserRequest} data - User data
* @returns {Promise<User>} Created user
* @throws {ValidationError} If data is invalid
* @throws {ConflictError} If email already exists
*/
export async function createUser(data: CreateUserRequest): Promise<User> {
// Implementation
}Python Docstrings (FastAPI)
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional
app = FastAPI(
title="User Management API",
description="API for managing users and authentication",
version="1.0.0",
docs_url="/docs",
redoc_url="/redoc"
)
class User(BaseModel):
"""
User model representing a user account.
Attributes:
id: Unique user identifier
name: User's full name
email: User's email address
role: User role (user or admin)
"""
id: str
name: str
email: str
role: str = "user"
@app.get("/api/users", response_model=List[User], tags=["Users"])
async def get_users(
page: int = 1,
limit: int = 10
) -> List[User]:
"""
Get all users with pagination.
Args:
page: Page number (default: 1)
limit: Number of items per page (default: 10)
Returns:
List of users
Raises:
HTTPException: If unauthorized (401)
"""
# Implementation
return []
@app.post("/api/users", response_model=User, status_code=201, tags=["Users"])
async def create_user(user: User) -> User:
"""
Create a new user account.
Args:
user: User data including name, email, and optional role
Returns:
Created user object
Raises:
HTTPException: If validation fails (400)
HTTPException: If email already exists (409)
"""
# Implementation
return userDocumentation Templates
Markdown API Reference
# API Reference
Base URL: `https://api.example.com/v1`
## Authentication
All API requests require authentication using a Bearer token:
Authorization: Bearer YOUR_ACCESS_TOKEN
Get your access token by calling the `/auth/login` endpoint.
## Endpoints
### Users
#### Get All Users
GET /api/users
Retrieve a paginated list of users.
**Parameters**
| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| page | integer | query | No | Page number (default: 1) |
| limit | integer | query | No | Items per page (max: 100) |
**Response**
{ "data": [ { "id": "123", "name": "John Doe", "email": "john@example.com", "role": "user" } ], "meta": { "page": 1, "limit": 10, "total": 42, "totalPages": 5 } }
**Status Codes**
- `200 OK` - Success
- `401 Unauthorized` - Missing or invalid authentication
- `500 Internal Server Error` - Server error
**Example Request**
curl -X GET "https://api.example.com/v1/api/users?page=1&limit=10" \ -H "Authorization: Bearer YOUR_TOKEN"
const response = await fetch('https://api.example.com/v1/api/users?page=1&limit=10', { headers: { 'Authorization': 'Bearer YOUR_TOKEN' } }); const data = await response.json();
import requests
response = requests.get( 'https://api.example.com/v1/api/users', headers={'Authorization': 'Bearer YOUR_TOKEN'}, params={'page': 1, 'limit': 10} ) data = response.json()
#### Create User
POST /api/users
Create a new user account.
**Request Body**
{ "name": "John Doe", "email": "john@example.com", "password": "SecurePass123!", "role": "user" }
**Response**
{ "id": "123", "name": "John Doe", "email": "john@example.com", "role": "user", "createdAt": "2024-01-15T10:30:00Z" }
**Status Codes**
- `201 Created` - User created successfully
- `400 Bad Request` - Invalid request data
- `409 Conflict` - Email already exists
- `401 Unauthorized` - Authentication required
## Error Handling
All errors follow a consistent format:
{ "code": "ERROR_CODE", "message": "Human-readable error message", "details": { "field": "Additional error details" } }
### Common Error Codes
| Code | HTTP Status | Description |
| --- | --- | --- |
| UNAUTHORIZED | 401 | Authentication required |
| FORBIDDEN | 403 | Insufficient permissions |
| NOT_FOUND | 404 | Resource not found |
| VALIDATION_ERROR | 400 | Invalid input data |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
## Rate Limiting
API requests are limited to:
- **100 requests per minute** for authenticated users
- **20 requests per minute** for unauthenticated requests
Rate limit headers are included in all responses:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1610000000
## Pagination
All list endpoints support pagination with these parameters:
- `page` - Page number (default: 1)
- `limit` - Items per page (default: 10, max: 100)
Responses include pagination metadata:
{ "data": [...], "meta": { "page": 1, "limit": 10, "total": 100, "totalPages": 10 } }
## Versioning
The API uses URL versioning:
- Current version: `v1`
- Base URL: `https://api.example.com/v1`
Breaking changes will be introduced in new versions (v2, v3, etc.)
Getting Started Guide
# Getting Started
This guide will help you make your first API request.
## 1. Get Your API Key
Sign up at [https://example.com/signup](https://example.com/signup) to get your API key.
## 2. Make Your First Request
### Using curl
curl -X GET https://api.example.com/v1/api/users \ -H "Authorization: Bearer YOUR_API_KEY"
### Using JavaScript
const response = await fetch('https://api.example.com/v1/api/users', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } });
const users = await response.json(); console.log(users);
### Using Python
import requests
response = requests.get( 'https://api.example.com/v1/api/users', headers={'Authorization': 'Bearer YOUR_API_KEY'} )
users = response.json() print(users)
## 3. Create a Resource
curl -X POST https://api.example.com/v1/api/users \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe", "email": "john@example.com" }'
## 4. Handle Errors
Always check the response status:
try { const response = await fetch('https://api.example.com/v1/api/users', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } });
if (!response.ok) { const error = await response.json(); console.error('Error:', error.message); return; }
const data = await response.json(); console.log(data); } catch (error) { console.error('Network error:', error); }
## Next Steps
- Read the [API Reference](https://github.com/api-reference)
- Explore [code examples](https://github.com/examples)
- Check out [best practices](https://github.com/best-practices)
- Join our [developer community](https://community.example.com)
Documentation Generation Tools
Docusaurus (Facebook)
# Create new site
npx create-docusaurus@latest my-docs classic
# Install OpenAPI plugin
npm install docusaurus-plugin-openapi-docs
# Configure
# docusaurus.config.js
module.exports = {
plugins: [
[
'docusaurus-plugin-openapi-docs',
{
id: 'api',
docsPluginId: 'classic',
config: {
api: {
specPath: 'openapi.yaml',
outputDir: 'docs/api',
sidebarOptions: {
groupPathsBy: 'tag'
}
}
}
}
]
]
};
# Generate docs
npm run docusaurus gen-api-docs all
# Serve
npm run startSlate (Beautiful API Docs)
# Clone template
git clone https://github.com/slatedocs/slate.git my-api-docs
cd my-api-docs
# Install dependencies
bundle install
# Edit source/index.html.md
# Run server
bundle exec middleman server
# Build static site
bundle exec middleman buildReadMe.io
# Install CLI
npm install -g rdme
# Upload OpenAPI spec
rdme openapi openapi.yaml --key YOUR_README_API_KEY
# Sync with GitHub
rdme openapi openapi.yaml --github --key YOUR_README_API_KEYMkDocs (Python)
# Install
pip install mkdocs mkdocs-material
# Create new project
mkdocs new my-api-docs
cd my-api-docs
# Configure mkdocs.yml
site_name: My API Documentation
theme:
name: material
features:
- navigation.tabs
- navigation.sections
- toc.integrate
nav:
- Home: index.md
- Getting Started: getting-started.md
- API Reference: api-reference.md
- Examples: examples.md
# Serve locally
mkdocs serve
# Build
mkdocs buildCode Examples Generator
Automatic Code Generation
// From OpenAPI spec
const CodeGen = require('openapi-client-axios-typegen');
async function generateSDK() {
const api = await CodeGen.generateClient('openapi.yaml');
// Generated TypeScript client
const users = await api.getUsers({ page: 1, limit: 10 });
const newUser = await api.createUser({
name: 'John Doe',
email: 'john@example.com'
});
}Multi-Language Examples
// examples-generator.js
const examples = {
getUsersCurl: `curl -X GET "https://api.example.com/v1/api/users?page=1&limit=10" \\
-H "Authorization: Bearer YOUR_TOKEN"`,
getUsersJavaScript: `const response = await fetch('https://api.example.com/v1/api/users?page=1&limit=10', {
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const data = await response.json();`,
getUsersPython: `import requests
response = requests.get(
'https://api.example.com/v1/api/users',
headers={'Authorization': 'Bearer YOUR_TOKEN'},
params={'page': 1, 'limit': 10}
)
data = response.json()`,
getUsersGo: `client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.example.com/v1/api/users?page=1&limit=10", nil)
req.Header.Add("Authorization", "Bearer YOUR_TOKEN")
resp, _ := client.Do(req)`,
getUsersRuby: `require 'net/http'
uri = URI('https://api.example.com/v1/api/users?page=1&limit=10')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_TOKEN'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }`
};Best Practices
Documentation Content
- Write clear, concise descriptions
- Include code examples in multiple languages
- Provide real-world use cases
- Document all error codes
- Include rate limits and quotas
- Show authentication examples
- Explain pagination
- Document versioning strategy
Interactive Features
- Add "Try it out" functionality
- Include request/response examples
- Show syntax highlighting
- Provide copy-to-clipboard buttons
- Add search functionality
- Include navigation menu
Maintenance
- Keep docs synchronized with code
- Automate documentation generation
- Version documentation with API
- Review and update regularly
- Test all code examples
- Collect user feedback
SEO and Discovery
- Use descriptive titles
- Add meta descriptions
- Create sitemap
- Use proper heading structure
- Include keywords
- Make docs publicly accessible
Notes
- Auto-generate docs from OpenAPI specs when possible
- Include interactive API explorers
- Provide examples in multiple programming languages
- Keep documentation up-to-date with code changes
- Use version control for documentation
- Make documentation searchable
- Include getting started guides
- Document authentication thoroughly
- Show error handling examples
- Test all code examples before publishing
- Collect and incorporate user feedback
- Use consistent formatting and style