API Documentation Generator

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

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

### POST /users

Create a new user account.

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

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

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

# 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:
1. Thoroughly scan code files for route definitions
2. Extract information from docstrings and comments
3. Infer request/response structure from code
4. Note assumptions and recommend validation

#### Multiple API Versions

When multiple versions exist:
1. Document each version separately
2. Note differences between versions
3. Indicate which version is recommended
4. Document migration path if applicable

#### Incomplete Information

When information is missing:
1. Document what's known
2. Mark unknown sections with `[To be documented]`
3. Provide best-effort inferences with `(inferred from code)`
4. Suggest improvements to add missing details

#### GraphQL APIs

For GraphQL:
1. Extract schema from `.graphql` files or introspection
2. Document queries, mutations, and subscriptions
3. Include example queries with variables
4. 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:**

1. Search for OpenAPI spec files
2. Find `openapi.yaml` in `/docs` directory
3. Parse the spec to extract all endpoints, schemas, and auth
4. Organize by tags into separate files
5. Generate README with overview and navigation
6. Create endpoint files for each tag
7. Create schemas.md with all data models
8. Create errors.md with error codes
9. 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:**

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

### Example 3: Multiple Sources

**User request:**
> "Summarize the API documentation from all available sources"

**Response approach:**

1. Find OpenAPI spec for base structure
2. Find existing markdown docs for additional context
3. Scan code for endpoints not in spec
4. Merge information from all sources
5. Prioritize OpenAPI spec for conflicts
6. Add code-derived info where spec is incomplete
7. Generate unified documentation
8. 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](assets/api-doc-template.md) as a starting point for each documentation file. Adapt the structure based on the specific API being documented.