🇺🇸English

API Documentation Writer

Create comprehensive, developer-friendly API documentation.

Instructions

When a user needs API documentation:

1. Gather API Information :

   • API type (REST, GraphQL, WebSocket, gRPC)?
   • Authentication method (API key, OAuth, JWT)?
   • Base URL and versioning strategy?
   • Available endpoints and their purposes?
   • Request/response formats?
   • Rate limiting or usage restrictions?

2. Generate Complete Documentation Structure :

Overview Section :

 * What the API does (1-2 sentences)
 * Key capabilities
 * Getting started checklist
 * Support and resources

Authentication :

 * How to obtain credentials
 * Where to include auth tokens
 * Example authenticated request
 * Token refresh process (if applicable)

Base URL & Versioning:

 * Production and sandbox URLs
 * Version format (path, header, query param)
 * Current version and changelog link

Endpoints (for each endpoint):

 * HTTP method and path
 * Description of what it does
 * Path parameters
 * Query parameters
 * Request headers
 * Request body schema
 * Response codes and meanings
 * Response body schema
 * Example request (curl, JavaScript, Python)
 * Example response (formatted JSON)

Error Handling :

 * Standard error response format
 * Common error codes and meanings
 * Troubleshooting guide

Rate Limiting :

 * Limits and windows
 * Headers to check
 * How to handle rate limit errors

SDKs & Libraries:

 * Official client libraries
 * Community libraries
 * Installation instructions

Webhooks (if applicable):

 * Available webhook events
 * Setup process
 * Payload examples
 * Security verification

3. Format Output (REST API example):

     # [API Name] Documentation
     
     ## Overview
     
     [Brief description of what the API does]
     
     **Base URL**: `https://api.example.com/v1`
     
     **Authentication**: API Key via `Authorization` header
     
     ## Quick Start
     
     1. [Step 1]
     2. [Step 2]
     3. [Step 3]
     
     ## Authentication
     
     All requests require an API key in the `Authorization` header:
     
     

Authorization: Bearer YOUR_API_KEY

     Get your API key from [dashboard link].
     
     ## Endpoints
     
     ### GET /resource
     
     Retrieve a list of resources.
     
     **Parameters**:
     - `limit` (optional, integer): Number of results (max 100, default 10)
     - `offset` (optional, integer): Pagination offset (default 0)
     - `filter` (optional, string): Filter by field
     
     **Request Example**:
     ```bash
     curl -X GET "https://api.example.com/v1/resource?limit=10" \
       -H "Authorization: Bearer YOUR_API_KEY"
     

Response (200 OK):

     {
       "data": [
         {
           "id": "123",
           "name": "Example",
           "created_at": "2024-01-15T10:00:00Z"
         }
       ],
       "total": 100,
       "limit": 10,
       "offset": 0
     }
     

Response Codes :

 * `200` \- Success
 * `400` \- Bad request (invalid parameters)
 * `401` \- Unauthorized (invalid API key)
 * `429` \- Rate limit exceeded
 * `500` \- Server error

POST /resource

Create a new resource.

Request Body :

{
  "name": "string (required)",
  "description": "string (optional)",
  "metadata": "object (optional)"
}

Request Example :

curl -X POST "https://api.example.com/v1/resource" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Resource",
    "description": "A test resource"
  }'

Response (201 Created):

{
  "id": "124",
  "name": "My Resource",
  "description": "A test resource",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Handling

All errors follow this format:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required",
    "details": {
      "field": "name"
    }
  }
}

Common Error Codes :

 * `invalid_request` \- Malformed request
 * `authentication_failed` \- Invalid API key
 * `not_found` \- Resource doesn't exist
 * `rate_limit_exceeded` \- Too many requests
 * `internal_error` \- Server error

Rate Limiting

Limits : 1000 requests per hour

Headers :

 * `X-RateLimit-Limit`: Total requests allowed
 * `X-RateLimit-Remaining`: Requests remaining
 * `X-RateLimit-Reset`: Timestamp when limit resets

When rate limited, you'll receive a 429 status code.

Code Examples

JavaScript (Node.js)

const response = await fetch('https://api.example.com/v1/resource', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

Python

import requests

response = requests.get(
  'https://api.example.com/v1/resource',
  headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

Support

 * Documentation: <https://docs.example.com>
 * Support: [support@example.com](https://github.com/onewave-ai/claude-skills/blob/HEAD/api-documentation-writer/mailto:support@example.com)
 * Status: <https://status.example.com>

4. For GraphQL APIs , adapt to show:

 * Schema definitions
 * Query examples
 * Mutation examples
 * Subscription examples
 * Variables and directives

5. Documentation Best Practices :

 * Start with working example (copy-paste ready)
 * Show both request and response
 * Use realistic example data
 * Include error cases
 * Explain every parameter
 * Provide code examples in multiple languages
 * Use consistent formatting
 * Add "Try it" interactive examples when possible
 * Link related endpoints
 * Include changelog and versioning

6. Developer Experience Tips :

 * Include a "Quick Start" with working example in 60 seconds
 * Provide Postman collection or OpenAPI spec
 * Show common use cases and workflows
 * Include troubleshooting section
 * Add testing/sandbox environment
 * Provide SDKs with installation instructions
 * Include rate limiting details upfront
 * Show pagination patterns
 * Explain filtering and sorting options

Example Triggers

• "Write API documentation for my REST endpoints"
• "Create OpenAPI spec for my API"
• "Document this GraphQL schema"
• "Generate developer docs for my webhook API"
• "Write authentication guide for API"

Output Quality

Ensure documentation:

• Starts with working example
• Explains every parameter and field
• Shows realistic request/response examples
• Includes error handling
• Provides code samples in multiple languages
• Uses consistent formatting
• Is organized logically (most common operations first)
• Includes authentication clearly
• Covers edge cases and limitations
• Follows REST/GraphQL best practices
• Is scannable with good use of headers
• Includes interactive examples when possible

Generate comprehensive, developer-friendly API documentation that makes integration effortless.

Weekly Installs

88

Repository

onewave-ai/claude-skills

GitHub Stars

74

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode73

codex73

gemini-cli71

cursor71

github-copilot68

kimi-cli64