OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add sickn33/agentic-awesome-skills --skill api-documentation-generator
Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices
npx skills add sickn33/agentic-awesome-skills --skill api-documentation-generator
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:
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:
Export collection for easy testing:
@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 User
Creates a new user account.
**Endpoint:** `POST /api/v1/users`
**Authentication:** Required (Bearer token)
**Request Body:**
\`\`\`json
{
"email": "user@example.com", // 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": "user@example.com",
"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": "user@example.com",
"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: 'user@example.com',
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': 'user@example.com',
'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": "user@example.com",
"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": "user@example.com",
"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"
}
\`\`\`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'{
"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"
}
}
]
}