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

```bash
# 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):**
```python
@app.post("/users")
async def create_user(user: UserCreate):
    """
    Create a new user.

    Args:
        user: User creation data

    Returns:
        Created user object
    """
```

**JavaScript (Express):**
```javascript
/**
 * 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)

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

Create a new user account.
```

**Request details:**
```markdown
**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"
  }'
```

```python
import requests

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