api-documentation-generator – skill Lập trình cho agent AI

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

Bind documentation to the actual source revision, routing/middleware/schema and verified examples. Mark missing or inferred behavior; do not invent rate limits, password policy, token expiry or exhaustive error coverage. Use synthetic data and secret placeholders. Public user creation must not accept an arbitrary client-supplied admin role: omit it unless a separately authorized admin endpoint validates that capability. Generated OpenAPI fragments need complete referenced schemas/responses and spec validation; interactive Try It calls are real operations requiring an approved sandbox.

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": "[email protected]",      // Required: Valid email address
  "password": "SecurePass123!",     // Required: Min 8 chars, 1 uppercase, 1 number
  "name": "John Doe",               // Required: 2-50 characters
  "role": "user"                    // Server-assigned output; do not accept admin from public registration
}
\`\`\`

**Success Response (201 Created):**
\`\`\`json
{
  "id": "usr_1234567890",
  "email": "[email protected]",
  "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": "[email protected]",
    "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: '[email protected]',
    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': '[email protected]',
        '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": "[email protected]",
      "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": "[email protected]",
  "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

1. Introduction

• What the API does
• Base URL
• API version
• Support contact

2. Authentication

• How to authenticate
• Token management
• Security best practices

3. Quick Start

• Simple example to get started
• Common use case walkthrough

4. Endpoints

• Organized by resource
• Full details for each endpoint

5. Data Models

• Schema definitions
• Field descriptions
• Validation rules

6. Error Handling

• Error code reference
• Error response format
• Troubleshooting guide

7. Rate Limiting

• Limits and quotas
• Headers to check
• Handling rate limit errors

8. Changelog

• API version history
• Breaking changes
• Deprecation notices

9. SDKs and Tools

• Offici

… (nội dung đầy đủ có trong gói tải về)