Imported from YYC-Cube/YYC3-Knowledge-Base (YYC3-J/antigravity-awesome-skills/plugins/antigravity-awesome-skills/skills/api-documentation-generator/SKILL.md). Install upstream with npx skills add YYC-Cube/YYC3-Knowledge-Base --skill api-documentation-generator. Copyright stays with the author.

API Documentation Generator

Overview

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.

When to Use This Skill

Use when you need to document a new API
Use when updating existing API documentation
Use when your API lacks clear documentation
Use when onboarding new developers to your API
Use when preparing API documentation for external users
Use when creating OpenAPI/Swagger specifications

How It Works

Step 1: Analyze the API Structure

First, I'll examine your API codebase to understand:

Available endpoints and routes
HTTP methods (GET, POST, PUT, DELETE, etc.)
Request parameters and body structure
Response formats and status codes
Authentication and authorization requirements
Error handling patterns

Step 2: Generate Endpoint Documentation

For each endpoint, I'll create documentation including:

Endpoint Details:

HTTP method and URL path
Brief description of what it does
Authentication requirements
Rate limiting information (if applicable)

Request Specification:

Path parameters
Query parameters
Request headers
Request body schema (with types and validation rules)

Response Specification:

Success response (status code + body structure)
Error responses (all possible error codes)
Response headers

Code Examples:

cURL command
JavaScript/TypeScript (fetch/axios)
Python (requests)
Other languages as needed

Step 3: Add Usage Guidelines

I'll include:

Getting started guide
Authentication setup
Common use cases
Best practices
Rate limiting details
Pagination patterns
Filtering and sorting options

Step 4: Document Error Handling

Clear error documentation including:

All possible error codes
Error message formats
Troubleshooting guide
Common error scenarios and solutions

Step 5: Create Interactive Examples

Where possible, I'll provide:

Postman collection
OpenAPI/Swagger specification
Interactive code examples
Sample responses

Examples

Example 1: REST API Endpoint Documentation

## 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)
\`\`\`

Example 2: GraphQL API Documentation

## 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"
      }
    }
  ]
}
\`\`\`

Example 3: Authentication Documentation

## 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"
}
\`\`\`

Best Practices

✅ Do This

Be Consistent - Use the same format for all endpoints
Include Examples - Provide working code examples in multiple languages
Document Errors - List all possible error codes and their meanings
Show Real Data - Use realistic example data, not "foo" and "bar"
Explain Parameters - Describe what each parameter does and its constraints
Version Your API - Include version numbers in URLs (/api/v1/)
Add Timestamps - Show when documentation was last updated
Link Related Endpoints - Help users discover related functionality
Include Rate Limits - Document any rate limiting policies
Provide Postman Collection - Make it easy to test your API

❌ Don't Do This

Don't Skip Error Cases - Users need to know what can go wrong
Don't Use Vague Descriptions - "Gets data" is not helpful
Don't Forget Authentication - Always document auth requirements
Don't Ignore Edge Cases - Document pagination, filtering, sorting
Don't Leave Examples Broken - Test all code examples
Don't Use Outdated Info - Keep documentation in sync with code
Don't Overcomplicate - Keep it simple and scannable
Don't Forget Response Headers - Document important headers

Documentation Structure

Recommended Sections

Introduction
- What the API does
- Base URL
- API version
- Support contact
Authentication
- How to authenticate
- Token management
- Security best practices
Quick Start
- Simple example to get started
- Common use case walkthrough
Endpoints
- Organized by resource
- Full details for each endpoint
Data Models
- Schema definitions
- Field descriptions
- Validation rules
Error Handling
- Error code reference
- Error response format
- Troubleshooting guide
Rate Limiting
- Limits and quotas
- Headers to check
- Handling rate limit errors
Changelog
- API version history
- Breaking changes
- Deprecation notices
SDKs and Tools
- Official client libraries
- Postman collection
- OpenAPI specification

Common Pitfalls

Problem: Documentation Gets Out of Sync

Symptoms: Examples don't work, parameters are wrong, endpoints return different data Solution:

Generate docs from code comments/annotations
Use tools like Swagger/OpenAPI
Add API tests that validate documentation
Review docs with every API change

Problem: Missing Error Documentation

Symptoms: Users don't know how to handle errors, support tickets increase Solution:

Document every possible error code
Provide clear error messages
Include troubleshooting steps
Show example error responses

Problem: Examples Don't Work

Symptoms: Users can't get started, frustration increases Solution:

Test every code example
Use real, working endpoints
Include complete examples (not fragments)
Provide a sandbox environment

Problem: Unclear Parameter Requirements

Symptoms: Users send invalid requests, validation errors Solution:

Mark required vs optional clearly
Document data types and formats
Show validation rules
Provide example values

Tools and Formats

OpenAPI/Swagger

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'

Postman Collection

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"
      }
    }
  ]
}

Related Skills

@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 issues

Additional Resources

Pro 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!

Limitations

Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

api-documentation-generator

About