api-documentation-generator

API Documentation Generator

Overview

Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines.

Perfect for REST APIs, GraphQL APIs, and WebSocket APIs.

When to Use This Skill

Use when you need to document a new API
Use when updating existing API documentation
Use when your API lacks clear documentation
Use when onboarding new developers to your API
Use when preparing API documentation for external users
Use when creating OpenAPI/Swagger specifications

How It Works

Step 1: Analyze the API Structure

First, I'll examine your API codebase to understand:

Available endpoints and routes
HTTP methods (GET, POST, PUT, DELETE, etc.)
Request parameters and body structure
Response formats and status codes
Authentication and authorization requirements
Error handling patterns

Step 2: Generate Endpoint Documentation

For each endpoint, I'll create documentation including:

Endpoint Details:

HTTP method and URL path
Brief description of what it does
Authentication requirements
Rate limiting information (if applicable)

Request Specification:

Path parameters
Query parameters
Request headers
Request body schema (with types and validation rules)

Response Specification:

Success response (status code + body structure)
Error responses (all possible error codes)
Response headers

Code Examples:

cURL command
JavaScript/TypeScript (fetch/axios)
Python (requests)
Other languages as needed

Step 3: Add Usage Guidelines

I'll include:

Getting started guide
Authentication setup
Common use cases
Best practices
Rate limiting details
Pagination patterns
Filtering and sorting options

Step 4: Document Error Handling

Clear error documentation including:

All possible error codes
Error message formats
Troubleshooting guide
Common error scenarios and solutions

Step 5: Create Interactive Examples

Where possible, I'll provide:

Postman collection
OpenAPI/Swagger specification
Interactive code examples
Sample responses

Examples

Example 1: REST API Endpoint Documentation

Create User

Creates a new user account.

Endpoint: POST /api/v1/users

Authentication: Required (Bearer token)

Request Body: ```json { "email": "user@example.com", // Required: Valid email address "password": "SecurePass123!", // Required: Min 8 chars, 1 uppercase, 1 number "name": "John Doe", // Required: 2-50 characters "role": "user" // Optional: "user" or "admin" (default: "user") } ```

Success Response (201 Created): ```json { "id": "usr_1234567890", "email": "user@example.com", "name": "John Doe", "role": "user", "createdAt": "2026-01-20T10:30:00Z", "emailVerified": false } ```

Error Responses:

400 Bad Request - Invalid input data ```json { "error": "VALIDATION_ERROR", "message": "Invalid email format", "field": "email" } ```
409 Conflict - Email already exists ```json { "error": "EMAIL_EXISTS", "message": "An account with this email already exists" } ```
401 Unauthorized - Missing or invalid authentication token

Example Request (cURL): ```bash curl -X POST https://api.example.com/api/v1/users
-H "Authorization: Bearer YOUR_TOKEN"
-H "Content-Type: application/json"
-d '{ "email": "user@example.com", "password": "SecurePass123!", "name": "John Doe" }' ```

Example Request (JavaScript): ```javascript const response = await fetch('https://api.example.com/api/v1/users', { method: 'POST', headers: { 'Authorization': Bearer ${token}, 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'user@example.com', password: 'SecurePass123!', name: 'John Doe' }) });

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

Example Request (Python): ```python import requests

response = requests.post( 'https://api.example.com/api/v1/users', headers={ 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' }, json={ 'email': 'user@example.com', 'password': 'SecurePass123!', 'name': 'John Doe' } )

user = response.json() print(user) ```

Example 2: GraphQL API Documentation

User Query

Fetch user information by ID.

Query: ```graphql query GetUser($id: ID!) { user(id: $id) { id email name role createdAt posts { id title publishedAt } } } ```

Variables: ```json { "id": "usr_1234567890" } ```

Response: ```json { "data": { "user": { "id": "usr_1234567890", "email": "user@example.com", "name": "John Doe", "role": "user", "createdAt": "2026-01-20T10:30:00Z", "posts": [ { "id": "post_123", "title": "My First Post", "publishedAt": "2026-01-21T14:00:00Z" } ] } } } ```

Errors: ```json { "errors": [ { "message": "User not found", "extensions": { "code": "USER_NOT_FOUND", "userId": "usr_1234567890" } } ] } ```

Example 3: Authentication Documentation

Authentication

All API requests require authentication using Bearer tokens.

Getting a Token

Endpoint: POST /api/v1/auth/login

Request: ```json { "email": "user@example.com", "password": "your-password" } ```

Response: ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 3600, "refreshToken": "refresh_token_here" } ```

Using the Token

Include the token in the Authorization header:

``` Authorization: Bearer YOUR_TOKEN ```

Token Expiration

Tokens expire after 1 hour. Use the refresh token to get a new access token:

Endpoint: POST /api/v1/auth/refresh

Request: ```json { "refreshToken": "refresh_token_here" } ```

Best Practices

✅ Do This

Be Consistent - Use the same format for all endpoints
Include Examples - Provide working code examples in multiple languages
Document Errors - List all possible error codes and their meanings
Show Real Data - Use realistic example data, not "foo" and "bar"
Explain Parameters - Describe what each parameter does and its constraints
Version Your API - Include version numbers in URLs (/api/v1/)
Add Timestamps - Show when documentation was last updated
Link Related Endpoints - Help users discover related functionality
Include Rate Limits - Document any rate limiting policies
Provide Postman Collection - Make it easy to test your API

❌ Don't Do This

Don't Skip Error Cases - Users need to know what can go wrong
Don't Use Vague Descriptions - "Gets data" is not helpful
Don't Forget Authentication - Always document auth requirements
Don't Ignore Edge Cases - Document pagination, filtering, sorting
Don't Leave Examples Broken - Test all code examples
Don't Use Outdated Info - Keep documentation in sync with code
Don't Overcomplicate - Keep it simple and scannable
Don't Forget Response Headers - Document important headers

Documentation Structure

Recommended Sections

Introduction

What the API does
Base URL
API version
Support contact

Authentication

How to authenticate
Token management
Security best practices

Quick Start

Simple example to get started
Common use case walkthrough

Endpoints

Organized by resource
Full details for each endpoint

Data Models

Schema definitions
Field descriptions
Validation rules

Error Handling

Error code reference
Error response format
Troubleshooting guide

Rate Limiting

Limits and quotas
Headers to check
Handling rate limit errors

Changelog

API version history
Breaking changes
Deprecation notices

SDKs and Tools

Official client libraries
Postman collection
OpenAPI specification

Common Pitfalls

Problem: Documentation Gets Out of Sync

Symptoms: Examples don't work, parameters are wrong, endpoints return different data Solution:

Generate docs from code comments/annotations
Use tools like Swagger/OpenAPI
Add API tests that validate documentation
Review docs with every API change

Problem: Missing Error Documentation

Symptoms: Users don't know how to handle errors, support tickets increase Solution:

Document every possible error code
Provide clear error messages
Include troubleshooting steps
Show example error responses

Problem: Examples Don't Work

Symptoms: Users can't get started, frustration increases Solution:

Test every code example
Use real, working endpoints
Include complete examples (not fragments)
Provide a sandbox environment

Problem: Unclear Parameter Requirements

Symptoms: Users send invalid requests, validation errors Solution:

Mark required vs optional clearly
Document data types and formats
Show validation rules
Provide example values

Tools and Formats

OpenAPI/Swagger

Generate interactive documentation:

openapi: 3.0.0 info: title: My API version: 1.0.0 paths: /users: post: summary: Create a new user requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest'

Postman Collection

Export collection for easy testing:

{ "info": { "name": "My API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Create User", "request": { "method": "POST", "url": "{{baseUrl}}/api/v1/users" } } ] }

Related Skills

@doc-coauthoring
For collaborative documentation writing
@copywriting
For clear, user-friendly descriptions
@test-driven-development
For ensuring API behavior matches docs
@systematic-debugging
For troubleshooting API issues

Additional Resources

OpenAPI Specification
REST API Best Practices
GraphQL Documentation
API Design Patterns
Postman Documentation

Pro Tip: Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!