Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices
npxskills add sickn33/antigravity-awesome-skills--skill api-documentation-generatorLoading…
Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines.
Perfect for REST APIs, GraphQL APIs, and WebSocket APIs.
First, I'll examine your API codebase to understand:
For each endpoint, I'll create documentation including:
Endpoint Details:
Request Specification:
Response Specification:
Code Examples:
I'll include:
Clear error documentation including:
Where possible, I'll provide:
## Create User
Creates a new user account.
**Endpoint:** `POST /api/v1/users`
**Authentication:** Required (Bearer token)
**Request Body:**
\`\`\`json
{
"email": "[email protected]", // Required: Valid email address
"password": "SecurePass123!", // Required: Min 8 chars, 1 uppercase, 1 number
"name": "John Doe", // Required: 2-50 characters
"role": "user" // Optional: "user" or "admin" (default: "user")
}
\`\`\`
**Success Response (201 Created):**
\`\`\`json
{
"id": "usr_1234567890",
"email": "[email protected]",
"name": "John Doe",
"role": "user",
"createdAt": "2026-01-20T10:30:00Z",
"emailVerified": false
}
\`\`\`
**Error Responses:**
- `400 Bad Request` - Invalid input data
\`\`\`json
{
"error": "VALIDATION_ERROR",
"message": "Invalid email format",
"field": "email"
}
\`\`\`
- `409 Conflict` - Email already exists
\`\`\`json
{
"error": "EMAIL_EXISTS",
"message": "An account with this email already exists"
}
\`\`\`
- `401 Unauthorized` - Missing or invalid authentication token
**Example Request (cURL):**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "SecurePass123!",
"name": "John Doe"
}'
\`\`\`
**Example Request (JavaScript):**
\`\`\`javascript
const response = await fetch('https://api.example.com/api/v1/users', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: '[email protected]',
password: 'SecurePass123!',
name: 'John Doe'
})
});
const user = await response.json();
console.log(user);
\`\`\`
**Example Request (Python):**
\`\`\`python
import requests
response = requests.post(
'https://api.example.com/api/v1/users',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
},
json={
'email': '[email protected]',
'password': 'SecurePass123!',
'name': 'John Doe'
}
)
user = response.json()
print(user)
\`\`\`
## User Query
Fetch user information by ID.
**Query:**
\`\`\`graphql
query GetUser($id: ID!) {
user(id: $id) {
id
email
name
role
createdAt
posts {
id
title
publishedAt
}
}
}
\`\`\`
**Variables:**
\`\`\`json
{
"id": "usr_1234567890"
}
\`\`\`
**Response:**
\`\`\`json
{
"data": {
"user": {
"id": "usr_1234567890",
"email": "[email protected]",
"name": "John Doe",
"role": "user",
"createdAt": "2026-01-20T10:30:00Z",
"posts": [
{
"id": "post_123",
"title": "My First Post",
"publishedAt": "2026-01-21T14:00:00Z"
}
]
}
}
}
\`\`\`
**Errors:**
\`\`\`json
{
"errors": [
{
"message": "User not found",
"extensions": {
"code": "USER_NOT_FOUND",
"userId": "usr_1234567890"
}
}
]
}
\`\`\`
## Authentication
All API requests require authentication using Bearer tokens.
### Getting a Token
**Endpoint:** `POST /api/v1/auth/login`
**Request:**
\`\`\`json
{
"email": "[email protected]",
"password": "your-password"
}
\`\`\`
**Response:**
\`\`\`json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"refreshToken": "refresh_token_here"
}
\`\`\`
### Using the Token
Include the token in the Authorization header:
\`\`\`
Authorization: Bearer YOUR_TOKEN
\`\`\`
### Token Expiration
Tokens expire after 1 hour. Use the refresh token to get a new access token:
**Endpoint:** `POST /api/v1/auth/refresh`
**Request:**
\`\`\`json
{
"refreshToken": "refresh_token_here"
}
\`\`\`
Introduction
Authentication
Quick Start
Endpoints
Data Models
Error Handling
Rate Limiting
Changelog
SDKs and Tools
Symptoms: Examples don't work, parameters are wrong, endpoints return different data Solution:
Symptoms: Users don't know how to handle errors, support tickets increase Solution:
Symptoms: Users can't get started, frustration increases Solution:
Symptoms: Users send invalid requests, validation errors Solution:
Generate interactive documentation:
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/users:
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
Export collection for easy testing:
{
"info": {
"name": "My API",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Create User",
"request": {
"method": "POST",
"url": "{{baseUrl}}/api/v1/users"
}
}
]
}
@doc-coauthoring - For collaborative documentation writing@copywriting - For clear, user-friendly descriptions@test-driven-development - For ensuring API behavior matches docs@systematic-debugging - For troubleshooting API issuesPro Tip: Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.