API Docs

Purpose

Create comprehensive API documentation including OpenAPI/Swagger specs, endpoint references, authentication guides, and SDK documentation.

Activation Keywords

• api documentation, api docs
• openapi, swagger
• endpoint documentation
• rest api docs, graphql docs
• sdk documentation

Core Capabilities

1. OpenAPI Specification

• Full spec generation
• Schema definitions
• Example requests/responses
• Security schemes
• Versioning

2. Endpoint Documentation

• Method descriptions
• Parameter details
• Response formats
• Error codes
• Rate limits

3. Authentication Guides

• Auth flow documentation
• Token management
• Scope explanations
• Security best practices
• Example implementations

4. SDK Documentation

• Installation guides
• Quick start examples
• Method references
• Error handling
• Best practices

5. Interactive Examples

• cURL commands
• Language-specific examples
• Postman collections
• Live API playground
• Response samples

OpenAPI Template

openapi: 3.0.3
info:
  title: [API Name]
  description: |
    [API Description]

    ## Authentication
    [Auth description]

    ## Rate Limits
    [Rate limit info]
  version: 1.0.0
  contact:
    email: [email protected]

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

security:
  - bearerAuth: []

paths:
  /resource:
    get:
      summary: List resources
      description: Returns a paginated list of resources
      tags:
        - Resources
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Resource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

Endpoint Documentation Format

## Create User

Creates a new user account.

### Endpoint

POST /api/v1/users

### Authentication
Requires `admin` scope.

### Request Headers
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

### Request Body

{ "email": "[email protected]", "name": "John Doe", "role": "member" }

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address |
| name | string | Yes | User's full name |
| role | string | No | One of: admin, member |

### Response

#### Success (201 Created)

{ "id": "usrabc123", "email": "[email protected]", "name": "John Doe", "role": "member", "createdat": "2024-01-15T10:30:00Z" }

#### Errors
| Status | Code | Description |
|--------|------|-------------|
| 400 | INVALID_EMAIL | Email format invalid |
| 409 | EMAIL_EXISTS | Email already registered |
| 401 | UNAUTHORIZED | Invalid or missing token |

### Example

curl -X POST https://api.example.com/v1/users \ -H "Authorization: Bearer sklivexxx" \ -H "Content-Type: application/json" \ -d '{"email": "[email protected]", "name": "John"}'

Example Usage

User: "Document our /users endpoint"

API Docs Response:

## Users API

### List Users

GET /api/v1/users

Returns a paginated list of users.

#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| page | integer | 1 | Page number |
| limit | integer | 20 | Items per page (max 100) |
| status | string | all | Filter: active, inactive, all |

#### Response (200 OK)

{ "data": [ { "id": "usrabc123", "email": "[email protected]", "name": "John Doe", "status": "active", "createdat": "2024-01-15T10:30:00Z" } ], "pagination": { "page": 1, "limit": 20, "total": 150, "pages": 8 } }

#### cURL Example

curl https://api.example.com/v1/users?limit=10 \ -H "Authorization: Bearer $API_KEY"