API Documentation Generator Agent Skill

API Documentation Generator

Overview

Analyze 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.

Workflow

1. Discover API Information Sources

Scan the repository to identify all sources of API information:

Primary sources (in priority order):

• OpenAPI/Swagger specifications (.yaml, .yml, .json)
• Look in: root directory, /docs, /api, /spec, /openapi
• Files named: openapi.yaml, swagger.json, api-spec.yaml, etc.

• Code files with docstrings/comments
• Python: Flask/FastAPI route decorators, docstrings
• JavaScript/TypeScript: Express routes, JSDoc comments
• Java: Spring annotations, Javadoc
• Go: HTTP handler comments
• Ruby: Rails routes, YARD comments

• Existing documentation
• Markdown files in /docs, /documentation, /api-docs
• README files with API sections
• Wiki pages or doc site content

• Configuration files
• routes.rb, urls.py, routes.js
• API gateway configurations

Discovery 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"

2. Extract API Information

Based on discovered sources, extract key information:

From OpenAPI Specs

Parse YAML/JSON to extract:

• Base URL and server information
• All paths and operations (GET, POST, PUT, PATCH, DELETE)
• Request parameters (path, query, header, body)
• Response schemas and status codes
• Authentication/security schemes
• Data models/schemas
• Tags and operation groupings

From Code Comments/Docstrings

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:

• HTTP method and path
• Description from docstring/comment
• Parameters and types
• Return types
• Example usage if present

From Existing Documentation

Parse markdown files to extract:

• Endpoint descriptions
• Request/response examples
• Authentication details
• Rate limiting information
• Error codes

3. Organize Documentation Structure

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:

• Group by resource (users, products, orders)
• Group by OpenAPI tags if available
• Group by URL prefix if no tags
• Keep authentication, errors, and models separate

4. Generate Documentation Files

For each file, use the template from assets/api-doc-template.md as a guide.

README.md (Main Overview)

# 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]

Endpoint Files (e.g., 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']}")

Data Models File (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"

}

Error Reference (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 |

5. Include Code Examples

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

Create user

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

Get user details

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

6. Handle Special Cases

No OpenAPI Spec Available

When no OpenAPI spec exists:

• Thoroughly scan code files for route definitions
• Extract information from docstrings and comments
• Infer request/response structure from code
• Note assumptions and recommend validation

Multiple API Versions

When multiple versions exist:

• Document each version separately
• Note differences between versions
• Indicate which version is recommended
• Document migration path if applicable

Incomplete Information

When information is missing:

• Document what's known
• Mark unknown sections with [To be documented]
• Provide best-effort inferences with (inferred from code)
• Suggest improvements to add missing details

GraphQL APIs

For GraphQL:

• Extract schema from .graphql files or introspection
• Document queries, mutations, and subscriptions
• Include example queries with variables
• Document input types and return types

7. Quality Checks

Before finalizing documentation:

• ✅ All endpoints documented with HTTP method and path
• ✅ Request parameters clearly specified (type, required/optional)
• ✅ Response schemas documented with examples
• ✅ Authentication method explained
• ✅ Error responses documented
• ✅ Code examples provided for main operations
• ✅ Files organized logically by resource
• ✅ Links between files work correctly
• ✅ Consistent formatting throughout
• ✅ Base URL and versioning strategy documented

Example Workflows

Example 1: Repository with OpenAPI Spec

User request:

> "Generate API documentation for this repository"

Response approach:

• Search for OpenAPI spec files
• Find openapi.yaml in /docs directory
• Parse the spec to extract all endpoints, schemas, and auth
• Organize by tags into separate files
• Generate README with overview and navigation
• Create endpoint files for each tag
• Create schemas.md with all data models
• Create errors.md with error codes
• Add code examples in curl and Python

Example 2: Flask API Without Spec

User request:

> "Document the API endpoints in this Flask application"

Response approach:

• Search for Flask route decorators (@app.route, @blueprint.route)
• Extract endpoints from route definitions
• Parse docstrings for descriptions and parameter info
• Infer request/response types from function signatures and code
• Organize endpoints by blueprint or URL prefix
• Generate documentation files
• Note inferred information with disclaimers
• Suggest creating OpenAPI spec for better docs

Example 3: Multiple Sources

User request:

> "Summarize the API documentation from all available sources"

Response approach:

• Find OpenAPI spec for base structure
• Find existing markdown docs for additional context
• Scan code for endpoints not in spec
• Merge information from all sources
• Prioritize OpenAPI spec for conflicts
• Add code-derived info where spec is incomplete
• Generate unified documentation
• Note sources for each piece of information

Tips for Effective Documentation

Be comprehensive but concise:

• Include all necessary details
• Avoid redundancy across files
• Use tables for structured data
• Use code blocks for examples

Use consistent formatting:

• Same structure for all endpoint docs
• Consistent naming (camelCase vs snake_case)
• Consistent status code documentation
• Consistent example format

Make it navigable:

• Clear table of contents in README
• Links between related sections
• Organized by resource or feature area
• Separate concerns (auth, errors, models)

Provide context:

• Explain what each endpoint does and why
• Show realistic use cases
• Include complete working examples
• Document edge cases and limitations

Keep it current:

• Extract from source of truth (code or spec)
• Note generated date
• Provide instructions for regenerating
• Flag areas needing manual review

Template

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.