#documentation

API Documentation Builder

Generate comprehensive API documentation from code with examples, types, and OpenAPI specs

Install

openclaw skills install @michaelatamuk/api-doc-builder

API Documentation Generator

No credentials required. This skill reads only local source files you point it at. The authentication examples throughout this document (Bearer tokens, API keys, OAuth) are patterns to document in your API docs — not credentials the skill itself needs or requests.

Automatically generates comprehensive, developer-friendly API documentation from your source code. Analyzes endpoints, parameters, return types, and generates documentation in multiple formats including Markdown, OpenAPI/Swagger specs, and interactive API explorers.

What This Skill Does

This skill analyzes your API code and generates complete documentation including:

Endpoint documentation with HTTP methods, paths, and descriptions
Parameter schemas with types, validation rules, and examples
Request/response examples with realistic sample data
Authentication requirements and security schemes
Error responses with status codes and error formats
OpenAPI 3.0 specifications for API tooling
TypeScript/JSDoc types for type safety
Interactive examples with curl, JavaScript, Python clients
Rate limiting and usage guidelines
Versioning information and deprecation notices

Supports multiple frameworks and languages:

Express.js / Fastify / Koa (Node.js)
Next.js API Routes / SvelteKit / Remix
FastAPI / Flask / Django REST (Python)
Gin / Echo / Chi (Go)
Spring Boot / Micronaut (Java)

Why Use This Skill

Saves Massive Time

Writing API documentation manually is tedious:

Manual docs: 2-4 hours per API
With this skill: 5-10 minutes to generate + 15 minutes to review
Time saved: 85-95% per API

Easier to Keep Up-to-Date

Regenerating is fast, so docs can follow code more closely:

Re-run after API changes to refresh documentation
Generated output reflects code at the time of analysis
Review generated docs before publishing — they are a starting point, not a guarantee
Always compare output against your actual implementation

Improves API Adoption

Well-documented APIs are used more:

73% of developers prefer good docs over SDKs
Clear examples reduce support requests by 60%
Interactive docs increase API adoption by 40%
Proper typing reduces integration errors

Enables Automation

Generated OpenAPI specs enable:

Client generation (SDKs for multiple languages)
API testing (automated contract testing)
API gateways (Kong, AWS API Gateway import)
Mocking (Prism, Mockoon for development)
Validation (request/response validation middleware)

When to Use This Skill

Use this skill whenever you need API documentation:

✅ New API development (document as you build)
✅ Legacy API documentation (retroactive docs)
✅ API versioning (track changes between versions)
✅ Public API launch (comprehensive user docs)
✅ Internal API catalog (microservices documentation)
✅ Client SDK generation (OpenAPI → code gen)
✅ API gateway integration (import specs)
✅ Contract testing setup (validate implementations)

When NOT to Use This Skill

❌ For private/internal implementation details (document public API only)
❌ For GraphQL APIs (use GraphQL introspection instead)
❌ For WebSocket/gRPC (different documentation approaches)
❌ When code lacks type information (add types first)
❌ For non-REST APIs (this focuses on REST/HTTP)

How It Works

Step-by-Step Process

Analyzes route definitions: Extracts HTTP methods, paths, middleware
Parses function signatures: Identifies parameters, request bodies, responses
Reads TypeScript types: Uses type information for schemas
Extracts JSDoc comments: Incorporates developer-written descriptions
Detects validation: Identifies Zod, Joi, class-validator rules
Generates examples: Creates realistic request/response samples
Builds OpenAPI spec: Produces valid OpenAPI 3.0 YAML/JSON
Creates markdown docs: Human-readable documentation
Adds interactive elements: curl examples, code snippets

Documentation Structure

For each endpoint:

HTTP method and path
Summary and detailed description
Authentication requirements
Request parameters (path, query, headers, body)
Response schemas (success and error cases)
Example requests and responses
Rate limiting and usage notes

Usage Examples

Example 1: Express.js REST API

Your code:

typescript

// src/api/users.ts
import { Router } from 'express';
import { z } from 'zod';

const router = Router();

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
  age: z.number().int().min(18).optional()
});

/**
 * Create a new user
 * @auth Required - Bearer token
 * @ratelimit 10 requests per minute
 */
router.post('/users', async (req, res) => {
  const data = CreateUserSchema.parse(req.body);
  const user = await db.users.create(data);
  res.status(201).json(user);
});

/**
 * Get user by ID
 * @param id - User ID (UUID format)
 */
router.get('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json(user);
});

export default router;

Ask Claude:

text

"Generate API documentation for the users API in src/api/users.ts"

Generated Markdown Documentation:

markdown

# Users API

## Endpoints

### Create User

Creates a new user account.

**Endpoint:** `POST /users`

**Authentication:** Required (Bearer token)

**Rate Limit:** 10 requests per minute

**Request Body:**
```json
{
  "email": "user@example.com",
  "name": "John Doe",
  "age": 25
}

Request Schema:

Field	Type	Required	Validation	Description
email	string	Yes	Valid email format	User email address
name	string	Yes	Min 2 characters	User full name
age	integer	No	Min 18	User age (must be 18+)

Success Response (201 Created):

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "age": 25,
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses:

400 Bad Request - Invalid input data

json

{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

401 Unauthorized - Missing or invalid authentication

json

{
  "error": "Authentication required"
}

429 Too Many Requests - Rate limit exceeded

json

{
  "error": "Rate limit exceeded",
  "retryAfter": 45
}

Example Request:

bash

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "email": "john@example.com",
    "name": "John Doe",
    "age": 25
  }'

Example Request (JavaScript):

javascript

const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({
    email: 'john@example.com',
    name: 'John Doe',
    age: 25
  })
});

const user = await response.json();
console.log(user);

Get User by ID

Retrieves a user by their unique identifier.

Endpoint: GET /users/:id

Authentication: Not required

Path Parameters:

Parameter	Type	Format	Description
id	string	UUID	User unique identifier

Success Response (200 OK):

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "age": 25,
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses:

404 Not Found - User does not exist

json

{
  "error": "User not found"
}

Example Request:

bash

curl https://api.example.com/users/550e8400-e29b-41d4-a716-446655440000

Example Request (JavaScript):

javascript

const userId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(`https://api.example.com/users/${userId}`);
const user = await response.json();

text


**Generated OpenAPI Specification:**
```yaml
openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
  description: User management endpoints

servers:
  - url: https://api.example.com
    description: Production server

paths:
  /users:
    post:
      summary: Create User
      description: Creates a new user account
      operationId: createUser
      tags:
        - Users
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                name:
                  type: string
                  minLength: 2
                  example: John Doe
                age:
                  type: integer
                  minimum: 18
                  example: 25
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'

  /users/{id}:
    get:
      summary: Get User by ID
      description: Retrieves a user by their unique identifier
      operationId: getUserById
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: User unique identifier
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: John Doe
        age:
          type: integer
          example: 25
        createdAt:
          type: string
          format: date-time
          example: 2024-01-15T10:30:00Z

    Error:
      type: object
      properties:
        error:
          type: string
          example: An error occurred

    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation failed
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string

    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded
        retryAfter:
          type: integer
          example: 45

Example 2: Next.js API Routes

Your code:

typescript

// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const page = parseInt(searchParams.get('page') || '1');
  const limit = parseInt(searchParams.get('limit') || '10');

  const posts = await db.posts.findMany({
    skip: (page - 1) * limit,
    take: limit,
    orderBy: { createdAt: 'desc' }
  });

  return NextResponse.json({
    data: posts,
    pagination: {
      page,
      limit,
      total: await db.posts.count()
    }
  });
}

export async function POST(request: NextRequest) {
  const body = await request.json();

  // Validation
  if (!body.title || !body.content) {
    return NextResponse.json(
      { error: 'Title and content are required' },
      { status: 400 }
    );
  }

  const post = await db.posts.create({
    data: {
      title: body.title,
      content: body.content,
      authorId: body.authorId
    }
  });

  return NextResponse.json(post, { status: 201 });
}

Ask Claude:

text

"Generate API docs for the posts API routes"

Generated Documentation includes:

GET /api/posts with pagination query parameters
POST /api/posts with request body schema
Response schemas for both endpoints
Error handling documentation
Pagination details
Example requests in multiple languages

Example 3: FastAPI (Python)

Your code:

python

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr

app = FastAPI()

class CreateUser(BaseModel):
    email: EmailStr
    name: str
    age: int | None = None

@app.post("/users", response_model=User, status_code=201)
async def create_user(user_data: CreateUser):
    """
    Create a new user.

    - **email**: Valid email address
    - **name**: User's full name
    - **age**: Optional age (must be 18+)
    """
    if user_data.age and user_data.age < 18:
        raise HTTPException(status_code=400, detail="Must be 18 or older")

    user = await db.create_user(user_data)
    return user

Ask Claude:

text

"Generate OpenAPI docs for this FastAPI application"

Generated: Complete OpenAPI spec with Pydantic model schemas automatically converted.

Configuration

Specify Output Format

text

"Generate Markdown API documentation"
"Create OpenAPI 3.0 specification in YAML"
"Generate both Markdown docs and OpenAPI spec"
"Create Postman collection from this API"

Customize Documentation Style

text

"Generate API docs in README format"
"Create comprehensive API reference with all examples"
"Generate minimal API docs (endpoints and parameters only)"

Include/Exclude Sections

text

"Generate API docs without rate limiting info"
"Include authentication details in the documentation"
"Add TypeScript client examples to the docs"

Best Practices

For Best Results

Add JSDoc comments: Claude uses them for descriptions
Use TypeScript types: Better schema generation
Define validation schemas: Zod, Joi, class-validator
Document auth requirements: Comment with @auth tags
Include examples in code: Sample data helps generate realistic examples
Group related endpoints: Organize by resource (users, posts, etc.)

Documentation Quality Checklist

Ensure generated docs include:

✅ Clear endpoint descriptions
✅ All required and optional parameters
✅ Realistic example requests/responses
✅ Error response documentation
✅ Authentication requirements
✅ Rate limiting information
✅ Versioning details

Keeping Docs Updated

bash

# Regenerate after API changes
"Regenerate API documentation after recent changes"

# Compare versions
"Show API changes between v1 and v2"

# Generate changelog
"Create API changelog from code changes"

Integration with Tools

Swagger UI

Host interactive API docs:

bash

npm install swagger-ui-express

# server.ts
import swaggerUi from 'swagger-ui-express';
import swaggerDocument from './openapi.json';

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Postman

Import OpenAPI spec:

Open Postman
Import → Link → Paste OpenAPI URL
Generate collection with all endpoints

Redoc

Beautiful API documentation:

bash

npm install redoc-cli
npx redoc-cli serve openapi.yaml

Client Generation

Generate typed API clients:

bash

# TypeScript client
npx openapi-typescript-codegen --input openapi.yaml --output ./src/api

# Python client
openapi-generator generate -i openapi.yaml -g python -o ./client

# Go client
openapi-generator generate -i openapi.yaml -g go -o ./client

API Gateway Integration

Import to cloud providers:

bash

# AWS API Gateway
aws apigateway import-rest-api --body file://openapi.yaml

# Google Cloud Endpoints
gcloud endpoints services deploy openapi.yaml

# Kong Gateway
deck sync --spec openapi.yaml

Advanced Features

Versioned Documentation

text

"Generate API docs for v2 with changes from v1"
"Create migration guide from v1 to v2"
"Show deprecated endpoints in v2 documentation"

Multi-Language Examples

text

"Add Python and Go client examples"
"Include examples for curl, JavaScript, and Ruby"

Interactive Examples

text

"Generate Swagger UI compatible spec"
"Create Stoplight-compatible documentation"

Documenting Your API's Auth Requirements

These are example prompts for documenting your API's security — the skill itself needs no credentials:

text

"Document the OAuth 2.0 authentication flow for the API"
"Add API key usage instructions to the docs"
"Describe JWT token validation in the authentication section"

Troubleshooting

Issue: Missing endpoint documentation

Cause: Route not detected or commented out.

Solution:

Ensure routes are exported and active
Check for TypeScript errors
Verify framework compatibility

Issue: Incorrect parameter types

Cause: Missing TypeScript types or validation schemas.

Solution:

text

"Regenerate docs using Zod schema for type information"

Add explicit types:

typescript

interface CreateUserRequest {
  email: string;
  name: string;
}

router.post('/users', async (req: Request<{}, {}, CreateUserRequest>, res) => {
  // ...
});

Issue: Examples are not realistic

Cause: No example data in code.

Solution: Add JSDoc examples:

typescript

/**
 * @example
 * {
 *   "email": "realistic@example.com",
 *   "name": "Jane Smith"
 * }
 */

Issue: Authentication not documented

Cause: Middleware not detected.

Solution: Add explicit comments:

typescript

/**
 * @auth bearer
 * @scope users:write
 */
router.post('/users', authMiddleware, handler);

Output Formats

Markdown

Human-readable documentation
Great for GitHub README
Version control friendly
Easy to customize

OpenAPI 3.0 (YAML/JSON)

Machine-readable specification
Tool ecosystem support
Client generation
API gateway integration

HTML

Static site documentation
Styled with CSS
No server required
Deployable to GitHub Pages

Postman Collection

Import directly to Postman
Includes example requests
Environment variables setup
Pre-request scripts

Real-World Use Cases

Startup API Launch

Before:

2 weeks manual documentation
Outdated within days
Missing examples
Developer complaints

After (with this skill):

2 hours total (generate + review)
Regenerate in 10 minutes
Comprehensive examples
Developer satisfaction up 85%

Microservices Documentation

Challenge: 20+ internal APIs, no central docs

Solution:

text

"Generate API catalog for all microservices in services/"

Result:

Complete API inventory
Consistent documentation style
Easy onboarding for new developers
Reduced integration time by 60%

Public API Productization

Goal: Launch developer platform

Process:

Generate comprehensive docs
Add interactive examples
Create client SDKs from OpenAPI
Deploy Swagger UI
Set up API gateway with spec

Outcome: API adoption 3× higher than manual docs

Best Practices for API Design

While documenting, consider these principles:

RESTful Conventions

Use nouns for resources: /users not /getUsers
HTTP methods for actions: GET, POST, PUT, DELETE
Plural resource names: /users not /user
Nested resources: /users/:id/posts

Consistent Naming

snake_case or camelCase (pick one)
Consistent error formats
Standard HTTP status codes
Predictable pagination

Versioning

URL versioning: /v1/users
Header versioning: Accept: application/vnd.api.v1+json
Deprecation warnings in docs
Migration guides between versions

Related Resources

Pro Tip: Generate docs early and often. Having documentation as you build helps you design better APIs and catches inconsistencies before they ship!

License: MIT-0 (Public Domain)

API Documentation Builder

Install

API Documentation Generator

What This Skill Does

Why Use This Skill

Saves Massive Time

Easier to Keep Up-to-Date

Improves API Adoption

Enables Automation

When to Use This Skill

When NOT to Use This Skill

How It Works

Step-by-Step Process

Documentation Structure

Usage Examples

Example 1: Express.js REST API

Get User by ID

Example 2: Next.js API Routes

Example 3: FastAPI (Python)

Configuration

Specify Output Format

Customize Documentation Style

Include/Exclude Sections

Best Practices

For Best Results

Documentation Quality Checklist

Keeping Docs Updated

Integration with Tools

Swagger UI

Postman

Redoc

Client Generation

API Gateway Integration

Advanced Features

Versioned Documentation

Multi-Language Examples

Interactive Examples

Documenting Your API's Auth Requirements

Troubleshooting

Issue: Missing endpoint documentation

Issue: Incorrect parameter types

Issue: Examples are not realistic

Issue: Authentication not documented

Output Formats

Markdown

OpenAPI 3.0 (YAML/JSON)

HTML

Postman Collection

Real-World Use Cases

Startup API Launch

Microservices Documentation

Public API Productization

Best Practices for API Design

RESTful Conventions

Consistent Naming

Versioning

Related Resources

Related skills