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: api@example.com

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
```json
{
  "email": "user@example.com",
  "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": "usr_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member",
  "created_at": "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 sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "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": "usr_abc123",
      "email": "user@example.com",
      "name": "John Doe",
      "status": "active",
      "created_at": "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"