api-documentation

API Documentation Skill

Generate clear, complete, professional API documentation from any form of API input.

Supported Input Formats

Accept any of the following as input:

• OpenAPI / Swagger (YAML or JSON, v2 or v3)
• Endpoint list (plain text, e.g. GET /users/:id)
• Route definitions (Express, FastAPI, Django, Rails, etc.)
• Controller / handler code (infer from function signatures and decorators)
• Informal descriptions ("I have an endpoint that creates a user and takes name + email")
• Postman collections (JSON)
• gRPC proto files (document as method-based API)
• GraphQL schema (document as query/mutation reference)

If the input is ambiguous, make reasonable inferences and note assumptions clearly.

Output Structure

Produce documentation with these sections, omitting any that are not applicable:

1. Overview

• API name and short description
• Base URL (if known or inferable)
• Authentication method(s) (API key, Bearer token, OAuth2, etc.)
• Versioning scheme (if present)
• General conventions (date formats, pagination, error codes)

2. Authentication

• How to authenticate
• Token/key location (header, query param, cookie)
• Example header or request snippet
• Token expiry / refresh flow (if mentioned)

3. Endpoints (one section per endpoint)

For each endpoint, document:

### [METHOD] /path/to/endpoint
**Summary**: One-line description of what this endpoint does.

**Description**: (Optional) Longer explanation, use cases, side effects.

**Authentication**: Required / Optional / None

#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id   | string | Yes    | Unique identifier of the resource |

#### Query Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| page | integer | No  | 1       | Page number for pagination |

#### Request Body
Content-Type: application/json

\`\`\`json
{
  "field": "value"
}
\`\`\`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| field | string | Yes    | Description of field |

#### Responses

**200 OK**
\`\`\`json
{
  "id": "abc123",
  "name": "Example"
}
\`\`\`

**400 Bad Request** — Validation error
**401 Unauthorized** — Missing or invalid token
**404 Not Found** — Resource does not exist
**500 Internal Server Error** — Unexpected server error

#### Example Request
\`\`\`bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[email protected]"}'
\`\`\`

#### Example Response
\`\`\`json
{
  "id": "u_abc123",
  "name": "Alice",
  "email": "[email protected]",
  "createdAt": "2026-03-20T10:00:00Z"
}
\`\`\`