API Documentation Generator

Overview

Generate comprehensive, structured API documentation by analyzing source code. The skill extracts endpoint definitions, HTTP methods, parameters, request/response schemas, authentication requirements, and error handling patterns, then produces documentation in both human-readable Markdown and machine-readable OpenAPI 3.0 JSON format.

When to use

• When the user asks to document an API or generate API docs
• When a codebase has REST endpoints that need reference documentation
• When migrating undocumented APIs and need to capture existing behavior
• When generating OpenAPI/Swagger specs from source code
• When the user mentions "API docs", "endpoint documentation", or "API reference"

Do NOT use when:

• The user needs to consume existing API docs (just read them directly)
• The API is already fully documented and the user wants to call it
• The user needs GraphQL schema docs (different structure, different tool)
• The task is writing API code, not documenting existing code

Workflow

1. Scan for route/endpoint definitions

Search the codebase for route registration patterns. Look for framework-specific patterns:

Output: A list of all endpoints with their file locations.

2. Extract HTTP methods, paths, and parameters

For each endpoint, extract:

• HTTP method (GET, POST, PUT, PATCH, DELETE)
• Path including path parameters (e.g., /users/:id)
• Query parameters from request parsing code
• Request body schema from validation or type definitions
• Response body from return statements or serializers
• Content types (JSON, form-data, multipart)

Parse path parameters from the route string. Look for query parameter access (req.query, request.args, @Query) and body parsing (req.body, request.json(), @Body).

3. Analyze request/response types

Trace type information from:

• TypeScript interfaces/types used in handlers
• Pydantic models, dataclasses, or serializers
• Zod/Joi/Yup validation schemas
• Database model definitions that map to responses
• JSDoc/docstring annotations

Build a schema for each request body and response body. Include field names, types, required/optional status, and constraints (min/max, regex, enum values).

4. Document authentication requirements

Look for:

• Middleware applied to routes (authenticate, requireAuth, jwt_required)
• Decorator-based auth (@login_required, @Depends(get_current_user))
• Guard classes (NestJS @UseGuards(AuthGuard))
• API key checks in handler code
• OAuth scopes or role-based access control

Document the auth scheme (Bearer token, API key, session cookie, OAuth2) and which endpoints require it. Note any role/permission requirements.

5. Generate error response documentation

Analyze error handling to document:

• Validation errors (400) - what triggers them, response format
• Authentication errors (401) - when auth fails or is missing
• Authorization errors (403) - permission denied scenarios
• Not found errors (404) - when resources don't exist
• Conflict errors (409) - duplicate resources, state conflicts
• Rate limit errors (429) - if rate limiting is present
• Server errors (500) - generic error response format

For each error, document the status code, error response schema, and conditions that trigger it. Look for custom error classes, error middleware, and exception handlers.

6. Add usage examples

For every endpoint, generate:

• A curl example showing a complete request with realistic data
• A success response example with realistic field values
• An error response example showing the most common failure case
• Request body examples for POST/PUT/PATCH endpoints

Use realistic but obviously fake data (e.g., user@example.com, not test@test.com). Include all required headers (Content-Type, Authorization).

7. Produce final structured output

Generate TWO output files:

api-docs.md - Human-readable Markdown documentation:

# API Reference

## Overview

Brief description of the API, base URL, and common patterns.

## Authentication

How to authenticate, token format, where to include credentials.

## Endpoints

### Resource Name

#### METHOD /path

Description of what this endpoint does.

**Parameters:**

| Name | In | Type | Required | Description |
| ---- | -- | ---- | -------- | ----------- |

**Request Body:**

```json
{ "example": "value" }
```

**Response (200):**

```json
{ "example": "response" }
```

**Error Responses:**

| Status | Description |
| ------ | ----------- |

**Example:**

```bash
curl -X METHOD https://api.example.com/path ...
```

openapi.json - OpenAPI 3.0 specification:

{
  "openapi": "3.0.3",
  "info": { "title": "API Name", "version": "1.0.0" },
  "paths": { "...": {} },
  "components": { "schemas": { "...": {} }, "securitySchemes": { "...": {} } }
}

Checklist

• All route/endpoint files identified and scanned
• Every endpoint has HTTP method, path, and description
• Path parameters, query parameters, and request bodies documented
• Request/response schemas include field types and constraints
• Authentication requirements documented per-endpoint
• Error responses documented with status codes and schemas
• Every endpoint has at least one curl example
• POST/PUT/PATCH endpoints have request body examples
• Output includes both api-docs.md and openapi.json
• OpenAPI spec is valid (correct structure, $ref usage)

Example

Input: Express.js route file

// routes/users.js
const express = require("express");
const router = express.Router();
const { authenticate } = require("../middleware/auth");
const { validate } = require("../middleware/validate");
const { body, param, query } = require("express-validator");

// GET /api/users - List users with pagination
router.get("/", authenticate, [
  query("page").optional().isInt({ min: 1 }).toInt(),
  query("limit").optional().isInt({ min: 1, max: 100 }).toInt(),
  query("role").optional().isIn(["admin", "user", "moderator"]),
], async (req, res) => {
  const { page = 1, limit = 20, role } = req.query;
  const users = await User.find(role ? { role } : {})
    .skip((page - 1) * limit)
    .limit(limit);
  const total = await User.countDocuments(role ? { role } : {});
  res.json({ users, total, page, limit });
});

// POST /api/users - Create a new user
router.post(
  "/",
  authenticate,
  [
    body("email").isEmail().normalizeEmail(),
    body("name").trim().isLength({ min: 2, max: 100 }),
    body("role").isIn(["admin", "user", "moderator"]),
    body("password").isLength({ min: 8 }),
  ],
  validate,
  async (req, res) => {
    const existing = await User.findOne({ email: req.body.email });
    if (existing) {
      return res.status(409).json({ error: "Email already registered" });
    }
    const user = await User.create(req.body);
    res.status(201).json({ user: user.toPublic() });
  },
);

// GET /api/users/:id - Get user by ID
router.get(
  "/:id",
  authenticate,
  [param("id").isMongoId()],
  validate,
  async (req, res) => {
    const user = await User.findById(req.params.id);
    if (!user) {
      return res.status(404).json({ error: "User not found" });
    }
    res.json({ user: user.toPublic() });
  },
);

Output: (excerpt from api-docs.md)

# API Reference

## Authentication

All endpoints require a Bearer token in the Authorization header:

    Authorization: Bearer <your-jwt-token>

## Endpoints

### Users

#### GET /api/users

List users with optional filtering and pagination.

**Query Parameters:**

| Name  | Type    | Required | Default | Description                               |
| ----- | ------- | -------- | ------- | ----------------------------------------- |
| page  | integer | No       | 1       | Page number (minimum: 1)                  |
| limit | integer | No       | 20      | Results per page (1-100)                  |
| role  | string  | No       | -       | Filter by role: admin, user, or moderator |

**Response (200 OK):**

```json
{
  "users": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "admin"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}
```

**Error Responses:**

| Status | Condition             | Body                                     |
| ------ | --------------------- | ---------------------------------------- |
| 401    | Missing/invalid token | `{ "error": "Unauthorized" }`            |
| 422    | Invalid query params  | `{ "errors": [{ "param": "...", ... }]}` |

**Example:**

```bash
curl -H "Authorization: Bearer eyJhbG..." \
  "https://api.example.com/api/users?page=1&limit=10&role=admin"
```

---

#### POST /api/users

Create a new user account.

**Request Body:**

| Field    | Type   | Required | Constraints                    |
| -------- | ------ | -------- | ------------------------------ |
| email    | string | Yes      | Valid email format             |
| name     | string | Yes      | 2-100 characters               |
| role     | string | Yes      | One of: admin, user, moderator |
| password | string | Yes      | Minimum 8 characters           |

```json
{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "user",
  "password": "secureP@ss123"
}
```

**Response (201 Created):**

```json
{
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "role": "user"
  }
}
```

**Error Responses:**

| Status | Condition             | Body                                      |
| ------ | --------------------- | ----------------------------------------- |
| 401    | Missing/invalid token | `{ "error": "Unauthorized" }`             |
| 409    | Email already exists  | `{ "error": "Email already registered" }` |
| 422    | Validation failed     | `{ "errors": [{ "param": "...", ... }]}`  |

**Example:**

```bash
curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","name":"Jane Smith","role":"user","password":"secureP@ss123"}'
```

Common mistakes

Quick reference

Key principles

1. Document every parameter - Every path param, query param, header, and body field must appear in the docs. Undocumented parameters are the #1 source of API integration bugs.

2. Include realistic examples - Every endpoint needs a curl example with realistic (but fake) data, a success response, and at least one error response. Developers copy-paste from docs; make it work.

3. Show error cases explicitly - Document every error status code with its trigger condition and response body. Developers spend more time debugging errors than writing happy-path code.

4. Maintain consistent structure - Every endpoint section must follow the same format: description, parameters table, request body, response, errors, example. Consistency lets developers scan quickly.

5. Dual output format - Always produce both human-readable Markdown and machine-readable OpenAPI JSON. The Markdown is for developers reading docs; the OpenAPI spec is for tooling (Postman, SDK generators, API gateways).