Advanced API Documentation Generator

A Claude Code skill for automatically generating clear, comprehensive API documentation from your codebase. Scans route handlers, controllers, and schemas to produce professional documentation with endpoints, parameters, request/response examples, authentication details, and error codes.

When to Use This Skill

Choose API Documentation Generator when:

• You want to auto-generate API docs from your existing codebase
• You need to create OpenAPI/Swagger specifications from route definitions
• You want to keep documentation in sync with your code
• You need to document REST APIs with examples and error codes
• You're onboarding developers who need to integrate with your API

Consider alternatives when:

• You need to design an API before implementation (use an API design skill)
• You want to integrate with external APIs (use an API integration skill)
• You need GraphQL documentation (use a GraphQL-specific skill)

Quick Start

Copy
# Install the skill
claude install advanced-api-documentation-generator

# Generate docs from codebase
claude "Generate API documentation for all routes in my Express.js app at /src/routes/"

# Create OpenAPI spec
claude "Create an OpenAPI 3.0 spec from my Next.js API routes at /src/app/api/"

# Update existing docs
claude "Update our API docs to include the new /api/v2/teams endpoints added last sprint"

Core Concepts

Documentation Structure

Section	Content	Source
Overview	API description, base URL, versioning	Manual + config
Authentication	Auth methods, token format, examples	Auth middleware
Endpoints	HTTP method, path, description	Route definitions
Parameters	Path, query, body params with types	Schema/validation
Request Examples	Sample request bodies	Generated from schemas
Response Examples	Sample responses for each status code	Generated from handlers
Error Codes	Error format, common error codes	Error handling middleware
Rate Limiting	Limits, headers, retry guidance	Rate limit config

Endpoint Documentation Template

Copy
## Create User
`POST /api/v1/users`

Creates a new user account.

**Authentication:** Bearer token required

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address |
| name | string | Yes | Full name |
| role | string | No | Role: admin, member (default: member) |

**Response:** `201 Created`
```json
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Jane Doe",
  "role": "member",
  "createdAt": "2026-03-13T10:00:00Z"
}

Errors:

Status	Code	Description
400	INVALID_EMAIL	Email format is invalid
409	EMAIL_EXISTS	Email already registered
401	UNAUTHORIZED	Missing or invalid token

### Auto-Detection Sources

| Framework | Route Source | Schema Source |
|-----------|------------|--------------|
| Express.js | `router.get/post/put/delete` | Joi, Zod, express-validator |
| Next.js | `app/api/**/route.ts` | Zod, TypeScript types |
| Fastify | Route definitions with schema | JSON Schema, TypeBox |
| NestJS | Controller decorators | class-validator, Swagger decorators |

## Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `format` | string | `"markdown"` | Output: markdown, openapi, html |
| `framework` | string | `"express"` | Framework: express, nextjs, fastify, nestjs |
| `include_examples` | boolean | `true` | Generate request/response examples |
| `group_by` | string | `"resource"` | Grouping: resource, method, path |
| `output_file` | string | `"api-docs.md"` | Output file path |

## Best Practices

1. **Generate from code, not manually** — Manual docs drift from implementation immediately. Generate docs from your route definitions, schemas, and types. This keeps documentation accurate without manual maintenance.

2. **Include realistic examples** — Auto-generated examples with "string" and 0 values are unhelpful. Create example generators that produce realistic data (real-looking emails, proper date formats, meaningful names).

3. **Document error responses as thoroughly as successes** — Developers spend more time debugging errors than handling successes. Every endpoint should document its possible error responses with status codes, error formats, and resolution guidance.

4. **Version your API and docs together** — When you release API v2, the docs should reflect v2. Keep versioned documentation so developers on v1 can still reference the correct docs.

5. **Add authentication examples** — Show complete curl examples including authentication headers. Developers copy-paste these to test quickly. A working curl command is worth more than paragraphs of authentication description.

## Common Issues

**Generated docs miss some endpoints** — The scanner may not recognize custom routing patterns. Ensure your routes follow standard framework conventions. For custom patterns, add JSDoc comments or decorators that the scanner can parse.

**Examples don't match actual responses** — Generated examples come from schemas, which may not include computed fields or nested relations. Supplement auto-generated examples with real API response snapshots.

**Docs are too long and hard to navigate** — Group endpoints by resource (users, teams, projects) with a table of contents. Add a quick-reference section at the top listing all endpoints with one-line descriptions.