Api Docs Generator

API Documentation Generator

Overview

Automatically generate clean, comprehensive API documentation from multiple source formats and save to /docs/API.md. Supports OpenAPI/Swagger specifications, Python/JavaScript/TypeScript docstrings, JSDoc/TSDoc comments, and inline Markdown documentation.

Quick Start

Provide API source code or specifications and specify the output location:

"Generate API docs from openapi.yaml and save to /docs/API.md"
"Create API documentation from these Python docstrings"
"Document this REST API and save to docs folder"

The skill will:

1. Parse the source format (OpenAPI, docstrings, JSDoc, etc.)
2. Extract endpoints, parameters, responses, and examples
3. Generate well-formatted Markdown documentation
4. Save to /docs/API.md or specified location

Detailed Instructions

Step 1: Identify Source Format

Recognize and parse different documentation sources:

OpenAPI/Swagger Specifications

YAML Format:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response

JSON Format:

{
  "openapi": "3.0.0",
  "info": {
    "title": "User API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "Get user by ID"
      }
    }
  }
}

Python Docstrings

Function Documentation:

def create_user(username: str, email: str, role: str = "user") -> dict:
    """
    Create a new user account.

    Args:
        username (str): The desired username (3-20 characters)
        email (str): User's email address
        role (str, optional): User role. Defaults to "user".

    Returns:
        dict: Created user object with id, username, email, and role

    Raises:
        ValueError: If username is already taken
        ValidationError: If email format is invalid

    Example:
        >>> create_user("john_doe", "john@example.com")
        {'id': 123, 'username': 'john_doe', 'email': 'john@example.com', 'role': 'user'}
    """
    pass

Class Documentation:

class UserAPI:
    """
    User management API endpoints.

    This class provides RESTful endpoints for user CRUD operations.
    All endpoints require authentication except for registration.

    Attributes:
        base_url (str): Base URL for all user endpoints
        timeout (int): Request timeout in seconds
    """

    def get_user(self, user_id: int) -> User:
        """
        Retrieve user by ID.

        GET /api/users/{user_id}

        Args:
            user_id: Unique user identifier

        Returns:
            User object with all details

        Raises:
            NotFoundError: If user doesn't exist
            AuthError: If not authenticated
        """
        pass

JSDoc/TSDoc Comments

JavaScript/TypeScript:

/**
 * Create a new user account
 *
 * @route POST /api/users
 * @param {Object} userData - User registration data
 * @param {string} userData.username - Desired username (3-20 chars)
 * @param {string} userData.email - Email address
 * @param {string} [userData.role=user] - User role
 * @returns {Promise} Created user object
 * @throws {ValidationError} If input validation fails
 * @throws {ConflictError} If username already exists
 *
 * @example
 * const user = await createUser({
 *   username: 'john_doe',
 *   email: 'john@example.com'
 * });
 */
async function createUser(userData: CreateUserDto): Promise {
  // implementation
}

/**
 * User API endpoints
 * @namespace UserAPI
 */

/**
 * Get user by ID
 *
 * @memberof UserAPI
 * @function getUser
 * @param {number} id - User ID
 * @returns {Promise} User object
 */

Inline Markdown Comments

/*
# User Management API

## Create User
**POST** `/api/users`

Creates a new user account.

### Request Body
```json
{
  "username": "string",
  "email": "string",
  "role": "string (optional)"
}

Response

200 OK

{
  "id": 123,
  "username": "john_doe",
  "email": "john@example.com",
  "role": "user"
}

Errors

• 400 - Validation error
• 409 - Username already exists

*/

### Step 2: Extract API Information

For each endpoint/function, extract:

**Core Information:**
- **Method**: GET, POST, PUT, DELETE, PATCH
- **Path**: /api/users, /api/users/{id}
- **Summary**: Brief description
- **Description**: Detailed explanation
- **Authentication**: Required auth type
- **Tags/Categories**: Grouping for organization

**Parameters:**
- **Path parameters**: {id}, {slug}
- **Query parameters**: ?page=1&limit=10
- **Header parameters**: Authorization, Content-Type
- **Request body**: Schema, required fields, types

**Responses:**
- **Success responses**: 200, 201, 204
- **Error responses**: 400, 401, 403, 404, 500
- **Response schemas**: JSON structure
- **Examples**: Sample requests and responses

**Additional Details:**
- **Deprecation warnings**
- **Rate limiting**
- **Versioning**
- **Security requirements**

### Step 3: Structure Documentation

Organize documentation in a clear, navigable format:

```markdown
# API Documentation

> **Base URL**: `https://api.example.com/v1`
> **Version**: 1.0.0
> **Last Updated**: 2024-12-16

## Table of Contents

- [Authentication](#authentication)
- [Users](#users)
  - [List Users](#list-users)
  - [Get User](#get-user)
  - [Create User](#create-user)
  - [Update User](#update-user)
  - [Delete User](#delete-user)
- [Posts](#posts)
- [Error Codes](#error-codes)

---

## Authentication

All API requests require authentication using Bearer tokens.

### Headers

```http
Authorization: Bearer 
Content-Type: application/json

Getting an API Token

1. Register for an account
2. Navigate to Settings > API Keys
3. Generate a new API key
4. Include in all requests

---

Users

List Users

Get a paginated list of all users.

Endpoint: GET /api/users

Authentication: Required

Query Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | page | integer | No | 1 | Page number | | limit | integer | No | 20 | Items per page (max 100) | | role | string | No | all | Filter by role (user, admin, moderator) | | search | string | No | - | Search by username or email |

Response: 200 OK

{
  "data": [
    {
      "id": 123,
      "username": "john_doe",
      "email": "john@example.com",
      "role": "user",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

Error Responses

| Code | Description | |------|-------------| | 401 | Unauthorized - Invalid or missing token | | 403 | Forbidden - Insufficient permissions | | 422 | Validation error - Invalid parameters |

Example Request

curl -X GET "https://api.example.com/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "data": [...],
  "pagination": {...}
}

---

Get User

Retrieve a specific user by ID.

Endpoint: GET /api/users/{id}

Authentication: Required

Path Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | User ID |

Response: 200 OK

{
  "id": 123,
  "username": "john_doe",
  "email": "john@example.com",
  "role": "user",
  "bio": "Software developer",
  "avatar_url": "https://example.com/avatars/123.jpg",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-02-20T14:45:00Z"
}

Error Responses

| Code | Description | |------|-------------| | 404 | User not found | | 401 | Unauthorized |

---

Create User

Create a new user account.

Endpoint: POST /api/users

Authentication: Admin only

Request Body

{
  "username": "string (required, 3-20 chars)",
  "email": "string (required, valid email)",
  "password": "string (required, min 8 chars)",
  "role": "string (optional, default: user)"
}

Field Validation

| Field | Type | Required | Validation | |-------|------|----------|------------| | username | string | Yes | 3-20 characters, alphanumeric + underscore | | email | string | Yes | Valid email format | | password | string | Yes | Minimum 8 characters, must include letter and number | | role | string | No | One of: user, moderator, admin |

Response: 201 Created

{
  "id": 124,
  "username": "new_user",
  "email": "new@example.com",
  "role": "user",
  "created_at": "2024-12-16T10:00:00Z"
}

Error Responses

| Code | Description | |------|-------------| | 400 | Validation error - Check error details | | 409 | Conflict - Username or email already exists | | 403 | Forbidden - Admin access required |

Example Request

curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_user",
    "email": "new@example.com",
    "password": "SecurePass123"
  }'

---

Error Codes

Standard Error Response

All errors return a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "username",
      "reason": "Already taken"
    }
  }
}

HTTP Status Codes

| Code | Meaning | Common Causes | |------|---------|---------------| | 400 | Bad Request | Invalid input, validation failure | | 401 | Unauthorized | Missing or invalid token | | 403 | Forbidden | Insufficient permissions | | 404 | Not Found | Resource doesn't exist | | 409 | Conflict | Duplicate resource | | 422 | Unprocessable Entity | Validation error | | 429 | Too Many Requests | Rate limit exceeded | | 500 | Internal Server Error | Server error |

Error Codes

| Code | Description | |------|-------------| | VALIDATION_ERROR | Input validation failed | | AUTHENTICATION_REQUIRED | Missing authentication | | INVALID_TOKEN | Token is invalid or expired | | INSUFFICIENT_PERMISSIONS | User lacks required permissions | | RESOURCE_NOT_FOUND | Requested resource doesn't exist | | DUPLICATE_RESOURCE | Resource already exists | | RATE_LIMIT_EXCEEDED | Too many requests |

---

Rate Limiting

• Limit: 100 requests per minute per API key
• Headers:
• X-RateLimit-Limit: Total requests allowed
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Timestamp when limit resets

When rate limit is exceeded:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  }
}

---

Versioning

API version is specified in the URL path:

• Current: /v1/
• Deprecated: /v0/ (sunset date: 2025-06-30)

Breaking changes will result in a new version. Non-breaking changes are added to the current version.

---

Changelog

Version 1.0.0 (2024-12-16)

• Initial API release
• User management endpoints
• Authentication with Bearer tokens

### Step 4: Format for Clarity

Apply consistent formatting:

**Headers and Sections:**
- Use clear hierarchy (H1 for title, H2 for resources, H3 for endpoints)
- Include table of contents for navigation
- Group related endpoints together

**Tables:**
- Use tables for parameters, fields, and error codes
- Include Type, Required, Default, and Description columns
- Keep tables concise and scannable

**Code Blocks:**
- Syntax highlight JSON, bash, etc.
- Include complete, runnable examples
- Show both request and response

**Visual Clarity:**
- Use blockquotes for important notes
- Use badges/tags for HTTP methods (GET, POST, etc.)
- Use emoji sparingly for visual markers (⚠️ for warnings)
- Consistent spacing between sections

**Cross-References:**
- Link to related endpoints
- Reference error codes section
- Link to authentication section

### Step 5: Save to /docs/API.md

**Default Location:**

/docs/API.md

**Alternative Locations:**

/docs/api/README.md /api-docs/API.md /documentation/API.md

**File Organization:**

For large APIs, consider splitting:

/docs/ ├── API.md # Overview and quick start ├── authentication.md # Auth details ├── users.md # User endpoints ├── posts.md # Post endpoints └── errors.md # Error reference

## Examples

### Example 1: OpenAPI Spec to Markdown

**Input (openapi.yaml):**
```yaml
openapi: 3.0.0
info:
  title: Task API
  version: 1.0.0
  description: Simple task management API

servers:
  - url: https://api.tasks.com/v1

paths:
  /tasks:
    get:
      summary: List all tasks
      tags:
        - Tasks
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, completed, archived]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'

    post:
      summary: Create a task
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 200
                description:
                  type: string
                due_date:
                  type: string
                  format: date
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Validation error

components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [pending, completed, archived]
        created_at:
          type: string
          format: date-time

Output (docs/API.md):

# Task API Documentation

> **Base URL**: `https://api.tasks.com/v1`
> **Version**: 1.0.0

Simple task management API

## Table of Contents

- [Tasks](#tasks)
  - [List Tasks](#list-tasks)
  - [Create Task](#create-task)
- [Models](#models)

---

## Tasks

### List Tasks

Get all tasks with optional filtering.

**Endpoint**: `GET /tasks`

**Query Parameters**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| status | string | No | Filter by status (pending, completed, archived) |

**Response: 200 OK**

```json
[
  {
    "id": 1,
    "title": "Complete project",
    "description": "Finish the API documentation",
    "status": "pending",
    "created_at": "2024-12-16T10:00:00Z"
  }
]

---

Create Task

Create a new task.

Endpoint: POST /tasks

Request Body

{
  "title": "string (required, 1-200 chars)",
  "description": "string (optional)",
  "due_date": "string (optional, date format)"
}

Field Validation

| Field | Type | Required | Validation | |-------|------|----------|------------| | title | string | Yes | 1-200 characters | | description | string | No | Any string | | due_date | string | No | ISO 8601 date format |

Response: 201 Created

{
  "id": 2,
  "title": "New task",
  "description": "Task description",
  "status": "pending",
  "created_at": "2024-12-16T11:00:00Z"
}

Error Responses

| Code | Description | |------|-------------| | 400 | Validation error |

---

Models

Task

{
  id:

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tomique34](https://github.com/tomique34)
- **Source:** [tomique34/claude-skill-creator](https://github.com/tomique34/claude-skill-creator)
- **License:** MIT

Install and usage instructions live in the source repository linked above.