api-documentation-generator

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)
2. Look in: root directory, /docs, /api, /spec, /openapi
3. Files named: openapi.yaml, swagger.json, api-spec.yaml, etc.

1. Code files with docstrings/comments
2. Python: Flask/FastAPI route decorators, docstrings
3. JavaScript/TypeScript: Express routes, JSDoc comments
4. Java: Spring annotations, Javadoc
5. Go: HTTP handler comments
6. Ruby: Rails routes, YARD comments

1. Existing documentation
2. Markdown files in /docs, /documentation, /api-docs
3. README files with API sections
4. Wiki pages or doc site content

1. Configuration files
2. routes.rb, urls.py, routes.js
3. 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](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": "john@example.com", "role": "admin" }

Response details:

**Response:**

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

**Body:**

{ "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:

**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": "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:

# 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": "john@example.com", "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": "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.