API Documentation Writer

The Problem

API documentation is either missing, auto-generated without context, or written once and never updated. Developers integrating with your API waste hours guessing parameter formats, decoding error responses, and reverse-engineering behavior from trial and error. Clear API docs with real examples cut integration time from days to hours.

The Prompt

You are a senior API technical writer. Generate comprehensive documentation for the following API endpoints:

ENDPOINTS:
[paste your route definitions, controller code, or OpenAPI spec here]

BASE URL: [e.g., https://api.example.com/v1]
AUTH METHOD: [e.g., Bearer token, API key in header, OAuth 2.0]

For each endpoint, document:
1. **Method & Path**: e.g., GET /users/:id
2. **Description**: What this endpoint does in one sentence
3. **Authentication**: Required auth level
4. **Parameters**: Table with name, location (path/query/body), type, required, description
5. **Request Example**: Complete curl command or fetch call
6. **Success Response**: Status code, response body with realistic sample data
7. **Error Responses**: All possible error codes with message format and when they occur
8. **Rate Limits**: If applicable

Format as clean Markdown suitable for a docs site.

Example Output

## GET /users/:id

Retrieve a single user by their unique identifier.

**Authentication**: Bearer token required (scope: `users:read`)

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| id | path | string (UUID) | yes | The user's unique identifier |
| fields | query | string | no | Comma-separated fields to include |

### Request

curl -H "Authorization: Bearer TOKEN" \
  https://api.example.com/v1/users/abc-123?fields=name,email

### 200 OK

{ "id": "abc-123", "name": "Jane Doe", "email": "jane@example.com" }

### Errors

| Status | Code | Description |
|--------|------|-------------|
| 401 | UNAUTHORIZED | Missing or invalid bearer token |
| 404 | USER_NOT_FOUND | No user exists with the given ID |
| 429 | RATE_LIMITED | Exceeded 100 requests per minute |

When to Use

Use this skill when building a new API, onboarding external developers, or documenting an existing API that only lives in the code. Feed it your route files or controller code for the best results. Also useful when converting internal API knowledge into a public developer portal.

Pro Tips

• Paste the actual route handler code — the AI extracts parameter validation, error handling, and response shapes directly from the implementation, catching details you might forget to document.
• Request an OpenAPI spec — append “Also generate the OpenAPI 3.0 YAML for these endpoints” to produce machine-readable docs alongside the human-readable Markdown.
• Include authentication flow — add “Document the complete auth flow from getting a token to making an authenticated request” so developers can go from zero to working API call.