API Endpoint Documenter

Generate comprehensive, developer-friendly API documentation directly from your codebase with accurate examples, type information, and interactive testing guides.

When to Use This Template

Choose API Endpoint Documenter when:

• You need to document REST, GraphQL, or WebSocket APIs from existing code
• Your API documentation has fallen out of sync with the actual implementation
• You want auto-generated OpenAPI/Swagger specs from route definitions
• New team members need clear integration guides for internal services

Consider alternatives when:

• You need full SDK generation (use an OpenAPI code generator instead)
• Your documentation is purely conceptual with no API endpoints
• You need a hosted documentation portal (use Redocly or ReadMe)

Quick Start

Copy
# .claude/skills/api-endpoint-documenter.yml
name: api-endpoint-documenter
description: Generate API documentation from route definitions
prompt: |
  Scan the codebase for API route definitions and generate
  comprehensive documentation for each endpoint.

  For every endpoint, document:
  1. HTTP method and path
  2. Request parameters (path, query, body) with types
  3. Response schema with example payloads
  4. Authentication requirements
  5. Error responses with status codes
  6. Rate limiting details if applicable

  Output format: Markdown with OpenAPI-compatible YAML blocks.

Example invocation:

Copy
claude "Document all endpoints in src/routes/ with request/response examples"

Sample output structure:

Copy
## POST /api/users

Create a new user account.

**Authentication:** Bearer token (admin role required)

**Request Body:**
| Field    | Type   | Required | Description          |
|----------|--------|----------|----------------------|
| email    | string | yes      | Valid email address   |
| name     | string | yes      | Full name (2-100 ch)  |
| role     | enum   | no       | "user" | "admin"      |

**Response 201:**
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Jane Doe",
  "createdAt": "2025-01-15T10:30:00Z"
}

**Error Responses:**
- 400: Validation failed (missing required fields)
- 409: Email already registered
- 401: Invalid or missing authentication token

Core Concepts

Documentation Extraction Pipeline

The documenter follows a systematic extraction process:

Phase	Action	Output
Discovery	Scan route files, controllers, handlers	Endpoint inventory
Type Analysis	Parse request/response types, schemas	Type definitions
Example Generation	Create realistic sample payloads	JSON examples
Auth Mapping	Identify middleware, guards, decorators	Auth requirements
Error Cataloging	Extract error handlers, status codes	Error reference
Assembly	Combine into structured documentation	Final docs

Framework-Specific Patterns

Copy
// Express.js route detection
// Scans: app.get(), router.post(), etc.
router.post('/api/users', authMiddleware, validate(userSchema), async (req, res) => {
  // Documenter extracts: method, path, middleware chain, validation schema
});

// Next.js API routes detection
// Scans: pages/api/**/*.ts or app/api/**/route.ts
export async function POST(request: Request) {
  // Documenter extracts: method from function name, path from file location
}

// FastAPI detection
// Scans: @app.get(), @router.post() decorators with Pydantic models
@router.post("/users", response_model=UserResponse, status_code=201)
async def create_user(user: UserCreate, db: Session = Depends(get_db)):
    # Documenter extracts: decorator params, Pydantic model fields, dependencies

OpenAPI Spec Generation

Copy
# Auto-generated OpenAPI 3.1 spec
openapi: "3.1.0"
info:
  title: "My API"
  version: "2.1.0"
paths:
  /api/users:
    post:
      summary: "Create user"
      operationId: "createUser"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserCreate"
      responses:
        "201":
          description: "User created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "400":
          description: "Validation error"

Configuration

Option	Type	Default	Description
scanPaths	string[]	["src/routes", "src/api"]	Directories to scan for routes
framework	string	"auto"	Framework detection: auto, express, nextjs, fastapi
outputFormat	string	"markdown"	Output: markdown, openapi-yaml, openapi-json
includeExamples	boolean	true	Generate example request/response payloads
authDocumentation	boolean	true	Document authentication requirements
groupBy	string	"resource"	Group endpoints by: resource, path, tag

Best Practices

1. Keep route definitions typed — Use TypeScript interfaces or Pydantic models for request/response bodies so the documenter can extract accurate schemas automatically rather than guessing types from runtime values.

2. Document edge cases in route comments — Add JSDoc or docstring annotations for business logic constraints (e.g., rate limits, field length limits, conditional required fields) that cannot be inferred from type definitions alone.

3. Version your API docs alongside code — Generate documentation as part of your CI pipeline and commit the output to the repository so docs are always in sync with the deployed API version.

4. Include authentication context — Document not just that auth is required, but which roles, scopes, or permissions are needed. The documenter extracts middleware chains, so keep auth middleware descriptive.

5. Provide realistic example data — Override auto-generated examples with domain-specific values when the defaults are not meaningful. A user email of "[email protected]" is more helpful than "string".

Common Issues

Endpoints missing from generated docs — The scanner could not find route definitions in the configured scan paths. Verify your scanPaths configuration matches your project structure. For Next.js App Router, ensure it scans app/api not pages/api. For monorepos, include all service directories.

Type information showing as "any" or "unknown" — The documenter cannot resolve request/response types because they are dynamically constructed or use any casts. Add explicit TypeScript interfaces to your route handlers or use Zod/Joi schemas that the documenter can parse for type extraction.

Generated examples contain placeholder values — When the documenter cannot infer realistic values from type names or validation rules, it falls back to generic placeholders. Add @example JSDoc tags to your type fields or provide an examples configuration file mapping field names to sample values.