API Docs Generator

API Documentation Generator

Automatically extract API routes from your codebase and generate comprehensive OpenAPI 3.0 specifications with proper schemas, examples, and descriptions.

Quick Start

When a user asks for API documentation, follow this checklist:

API Documentation Progress:
- [ ] Step 1: Detect API framework and analyze routes
- [ ] Step 2: Extract endpoint definitions
- [ ] Step 3: Infer request/response schemas
- [ ] Step 4: Generate OpenAPI specification
- [ ] Step 5: Create markdown documentation
- [ ] Step 6: Add examples and descriptions
- [ ] Step 7: Validate and output

Workflow

Step 1: Detect Framework and Analyze Routes

Run the route analyzer to detect the API framework and find all endpoints:

python .claude/skills/api-docs-generator/scripts/analyze_routes.py .

Supported Frameworks:

• Express.js / Fastify / Hono / NestJS (Node.js)
• FastAPI / Flask / Django REST (Python)
• Gin / Echo / Chi (Go)
• Next.js API Routes / App Router

Output includes:

• Framework detected
• Base URL/prefix
• List of all routes with methods
• Middleware detected (auth, validation)

Step 2: Extract Endpoint Definitions

For each detected endpoint, extract:

Express Example:

// Route: POST /api/users
// Extract: path params, body schema, response type
router.post("/", validateRequest(createUserSchema), userController.create);

Step 3: Infer Request/Response Schemas

Extract schemas from validation libraries and TypeScript types:

From Zod

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  role: z.enum(["admin", "user"]),
});
// → Infer OpenAPI schema with types, formats, constraints

From TypeScript Interfaces

interface UserResponse {
  id: string;
  email: string;
  createdAt: Date;
}
// → Convert to OpenAPI schema

From Pydantic (Python)

class UserCreate(BaseModel):
    email: EmailStr
    name: str = Field(..., min_length=2, max_length=100)
# → Convert to OpenAPI schema

Schema Mapping:

Step 4: Generate OpenAPI Specification

Create the OpenAPI 3.0 YAML/JSON file:

openapi: 3.0.3
info:
  title: { { API_NAME } }
  description: { { API_DESCRIPTION } }
  version: { { VERSION } }
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: http://localhost:3000
    description: Development
  - url: https://api.example.com
    description: Production

paths:
  /api/users:
    get:
      summary: List users
      operationId: listUsers
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
    post:
      summary: Create user
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserInput"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - name
        - createdAt

  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Step 5: Create Markdown Documentation

Generate human-readable API documentation:

python .claude/skills/api-docs-generator/scripts/generate_markdown.py openapi.yaml --output docs/API.md

Output Structure:

# API Documentation

## Authentication

Bearer token required for protected endpoints.

## Endpoints

### Users

#### List Users

`GET /api/users`

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| page | integer | No | Page number (default: 1) |
| limit | integer | No | Items per page (default: 20) |

**Response:**

```json
[
  {
    "id": "abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "createdAt": "2024-01-15T10:30:00Z"
  }
]
```

Create User

POST /api/users

Request Body:

{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}

...

---

### Step 6: Add Examples and Descriptions

Enhance documentation with:

1. **Request/Response Examples**
   - Generate realistic sample data
   - Include edge cases
   - Show error responses

2. **Descriptions**
   - Summarize each endpoint's purpose
   - Document business rules
   - Note rate limits and permissions

3. **Code Snippets**
   - cURL examples
   - JavaScript/fetch examples
   - Python requests examples

---

### Step 7: Validate and Output

Validate the generated OpenAPI spec:

```bash
python .claude/skills/api-docs-generator/scripts/validate_openapi.py openapi.yaml

Checks:

• Valid OpenAPI 3.0 syntax
• All $ref references resolve
• Required fields present
• Schema consistency

Output Files:

docs/
├── openapi.yaml          # OpenAPI 3.0 spec
├── openapi.json          # JSON version
├── API.md                # Markdown docs
└── postman_collection.json  # Postman import

Configuration

Create .claude/api-docs-config.yaml to customize:

info:
  title: My API
  version: 1.0.0
  description: Backend API for MyApp

servers:
  - url: http://localhost:3000
    description: Development
  - url: https://api.myapp.com
    description: Production

defaults:
  auth: BearerAuth
  content_type: application/json
  tag_from: folder # folder, file, or manual

output:
  format: yaml # yaml or json
  path: docs/openapi.yaml
  markdown: docs/API.md
  postman: true

ignore:
  - /health
  - /metrics
  - /internal/*

Framework-Specific Extraction

Express.js

// Patterns detected:
router.get("/users", handler); // Basic route
router.post("/users", validate, handler); // With middleware
app.use("/api", apiRouter); // Nested routers

FastAPI

# Patterns detected:
@router.get("/users", response_model=List[User])
@router.post("/users", status_code=201)
# + Pydantic models for schemas

Next.js App Router

// app/api/users/route.ts
export async function GET(request: Request) {}
export async function POST(request: Request) {}
// → Infer routes from file structure

NestJS

// Patterns detected:
@Controller('users')
@Get()
@Post()
@ApiOperation({ summary: 'List users' })  // Already has OpenAPI decorators

Examples

Example 1: Express API

User asks: "Generate OpenAPI docs for my API"

1. Run analyze_routes.py → Detects Express
2. Find routes in src/routes/*.ts
3. Extract Zod schemas from src/schemas/
4. Generate openapi.yaml
5. Create API.md

Example 2: FastAPI

User asks: "Create Swagger documentation"

1. Detect FastAPI
2. Parse routers with decorators
3. Extract Pydantic models
4. Generate spec (FastAPI has built-in support, enhance it)

Example 3: Next.js

User asks: "Document my Next.js API routes"

1. Scan app/api/** or pages/api/**
2. Infer routes from file structure
3. Parse request/response types
4. Generate documentation

Tips for Best Results

1. Use validation libraries - Zod, Pydantic, etc. provide schema info
2. Add TypeScript types - Help infer request/response shapes
3. Organize routes by resource - Creates better tags automatically
4. Include JSDoc/docstrings - Used for descriptions
5. Use consistent patterns - Easier to detect and extract

Related Skills

• fullstack-feature-generator - Generate APIs with built-in docs
• codebase-onboarding - Understand existing APIs first