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):

1. OpenAPI/Swagger specifications (.yaml, .yml, .json)

   • Look in: root directory, /docs, /api, /spec, /openapi
   • Files named: openapi.yaml, swagger.json, api-spec.yaml, etc.

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

3. Existing documentation

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

4. 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:**

```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin"
}

**Response details:**
```markdown
**Response:**

- **Status:** `201 Created`
- **Headers:**
  - `Location: /users/123`

**Body:**

```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Responses:

• 400 Bad Request - Invalid input data
• 409 Conflict - Email already exists

**Code examples:**
```markdown
**Example Request:**

```bash
curl -X POST "https://api.example.com/v1/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com"
  }'

import requests

response = requests.post(
    "https://api.example.com/v1/users",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "name": "John Doe",
        "email": "john@example.com"
    }
)

user = response.json()
print(f"Created user: {user['id']}")

#### Data Models File (`models/schemas.md`)

Document all data structures:

```markdown
# 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:**

```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

#### Error Reference (`errors.md`)

```markdown
# Error Handling

All errors follow this format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Error Codes

### 5. Include Code Examples

For major use cases, provide complete code examples:

```markdown
# Examples

## Creating and Managing Users

### 1. Create a User

```bash
curl -X POST "https://api.example.com/v1/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name": "John Doe", "email": "john@example.com"}'

import requests

# Create user
response = requests.post(
    "https://api.example.com/v1/users",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"name": "John Doe", "email": "john@example.com"}
)

user_id = response.json()["id"]

2.