API Documentation Writer

API Documentation Site
|
+-- Getting Started
|   +-- Quickstart (5-minute integration)
|   +-- Authentication Guide
|   +-- Rate Limits & Quotas
|   +-- Environments (sandbox, production)
|
+-- API Reference (auto-generated from OpenAPI)
|   +-- Endpoints grouped by resource
|   +-- Request/response schemas
|   +-- Code examples per endpoint
|   +-- Try-it-out console
|
+-- Guides
|   +-- Common Workflows
|   +-- Webhooks Integration
|   +-- Pagination Patterns
|   +-- Error Handling
|   +-- Migration Guides (v1 -> v2)
|
+-- SDKs & Libraries
|   +-- Installation
|   +-- Configuration
|   +-- Usage Examples
|   +-- Changelog
|
+-- Reference
|   +-- Error Codes
|   +-- Status Codes
|   +-- Glossary
|   +-- Changelog / Release Notes

openapi: 3.1.0
info:
  title: Orders API
  version: 2.1.0
  description: |
    The Orders API lets you create, get, update, and manage customer orders.

    ## Authentication
    All endpoints require a Bearer token. See [Authentication Guide](/docs/auth).

    ## Rate Limits
    - Standard: 100 requests/minute
    - Bulk endpoints: 10 requests/minute

    ## Versioning
    Include `API-Version: 2024-01-15` header. See [Versioning](/docs/versioning).
  contact:
    name: API Support
    email: api-support@company.com
    url: [reference URL]

servers:
  - url: [reference URL]
    description: Production
  - url: [reference URL]
    description: Sandbox (test data, no real charges)

tags:
  - name: Orders
    description: |
      Create and manage customer orders. Orders progress through states:
      `pending` -> `confirmed` -> `shipped` -> `delivered`.
      Orders can be `cancelled` before shipping.

paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create an order
      description: |
        Creates a new order for the authenticated customer.

        **Important:** The order is created in `pending` status and must be
        confirmed within 30 minutes or it will be automatically cancelled.

        Requires the `orders:write` scope.
      tags: [Orders]
      security:
        - BearerAuth: [orders:write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              simple_order:
                summary: Simple single-item order
                value:
                  items:
                    - product_id: "prod_abc123"
                      quantity: 2
                  shipping_address:
                    line1: "123 Main St"
                    city: "San Francisco"
                    state: "CA"
                    postal_code: "94102"
                    country: "US"
              multi_item:
                summary: Multi-item order with discount
                value:
                  items:
                    - product_id: "prod_abc123"
                      quantity: 2
                    - product_id: "prod_def456"
                      quantity: 1
                  discount_code: "SAVE10"
                  shipping_address:
                    line1: "456 Oak Ave"
                    city: "Austin"
                    state: "TX"
                    postal_code: "73301"
                    country: "US"
                  metadata:
                    source: "mobile_app"
                    campaign: "summer_sale"
      responses:
        '201':
          description: Order created successfully
          headers:
            X-Request-Id:
              description: Unique request identifier for support
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                created:
                  summary: Newly created order
                  value:
                    id: "ord_xyz789"
                    status: "pending"
                    items:
                      - product_id: "prod_abc123"
                        quantity: 2
                        unit_price: 29.99
                        total: 59.98
                    subtotal: 59.98
                    tax: 5.40
                    total: 65.38
                    created_at: "2024-06-15T10:30:00Z"
                    expires_at: "2024-06-15T11:00:00Z"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                invalid_product:
                  summary: Product not found
                  value:
                    error:
                      code: "INVALID_PRODUCT"
                      message: "Product 'prod_invalid' does not exist"
                      field: "items[0].product_id"
                out_of_stock:
                  summary: Product out of stock
                  value:
                    error:
                      code: "OUT_OF_STOCK"
                      message: "Product 'prod_abc123' has only 1 unit available"
                      field: "items[0].quantity"
                      metadata:
                        available_quantity: 1

components:
  schemas:
    Order:
      type: object
      description: Represents a customer order
      properties:
        id:
          type: string
          description: Unique order identifier
          example: "ord_xyz789"
          readOnly: true
        status:
          type: string
          description: |
            Current order status. Transitions:
            - `pending` -> `confirmed` (after payment)
            - `confirmed` -> `shipped` (after fulfillment)
            - `shipped` -> `delivered` (after delivery confirmation)
            - `pending|confirmed` -> `cancelled` (before shipping)
          enum: [pending, confirmed, shipped, delivered, cancelled]

# cURL
HTTP client request -X POST [reference URL] \
  -H "Authorization: Bearer sk_test_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "API-Version: 2024-01-15" \
  -d '{
    "items": [
      {"product_id": "prod_abc123", "quantity": 2}
    ],
    "shipping_address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    }
  }'

# Python
import company_sdk

client = company_sdk.Client(api_key="sk_test_EXAMPLE_KEY_REPLACE_ME")

order = client.orders.create(
    items=[
        {"product_id": "prod_abc123", "quantity": 2}
    ],
    shipping_address={
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94102",
        "country": "US",
    }
)

print(f"Order created: {order.id}")
print(f"Total: ${order.total}")

// Node.js
const Company = require('company-sdk');

const client = new Company('sk_test_EXAMPLE_KEY_REPLACE_ME');

const order = await client.orders.create({
  items: [
    { product_id: 'prod_abc123', quantity: 2 }
  ],
  shipping_address: {
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94102',
    country: 'US',
  }
});

console.log(`Order created: ${order.id}`);
console.log(`Total: $${order.total}`);

DO:
  - Show complete, copy-paste-ready examples
  - Include error handling in examples
  - Use realistic (but fake) data
  - Show the response alongside the request
  - Include the SDK version in installation instructions
  - Highlight the key parameters with inline comments

DON'T:
  - Use real API keys; use clearly-marked test keys (e.g., sk_test_EXAMPLE_KEY_REPLACE_ME)
  - Show only the happy path (include error handling)
  - Assume SDK is already installed (show installation)
  - Use outdated SDK methods
  - Skip import/require statements

# Quickstart: Create Your First Order

Get up and running with the Orders API in 5 minutes.

## Prerequisites
- A Company account ([sign up free]([reference URL]))
- An API key from [Dashboard > API Keys]([reference URL])

## Step 1: Install the SDK

Choose your language:

**Python** (requires Python 3.8+)
> install via pip: company-sdk

**Node.js** (requires Node 18+)
> install via npm: company-sdk

## Step 2: Make your first API call

[Code example: list products]

**Expected response:**
[Show formatted JSON response]

## Step 3: Create an order

[Code example: create order with error handling]

**Expected response:**
[Show the order object with status: "pending"]

## Step 4: Check order status

[Code example: get order by ID]

## Next Steps
- [Authentication Guide](/docs/auth) - Learn about API keys and OAuth
- [Webhooks](/docs/webhooks) - Get real-time order status updates
- [Full API Reference](/docs/api) - Explore all endpoints
- [Error Handling](/docs/errors) - Handle errors gracefully

# Structured error documentation
error_categories:
  authentication:
    - code: INVALID_API_KEY
      http_status: 401
      message: "The API key provided is invalid or expired"
      causes:
        - "API key was deleted or rotated"
        - "Using test key against production endpoint"
        - "Key has been compromised and revoked"
      resolution: "Generate a new API key in Dashboard > API Keys"

    - code: INSUFFICIENT_SCOPE
      http_status: 403
      message: "Your token lacks the required scope for this endpoint"
      causes:
        - "OAuth token was not granted the needed scope"
      resolution: "Request additional scopes during OAuth authorization"

  validation:
    - code: INVALID_PARAMETER
      http_status: 400
      message: "A required parameter is missing or invalid"
      fields:
        field: "The parameter that failed validation"
        expected: "What was expected"
        received: "What was received"
      example:
        error:
          code: "INVALID_PARAMETER"
          message: "quantity must be a positive integer"
          field: "items[0].quantity"
          expected: "integer > 0"
          received: "-1"

  rate_limiting:
    - code: RATE_LIMIT_EXCEEDED
      http_status: 429
      message: "Too many requests"
      headers:
        X-RateLimit-Limit: "Maximum requests per window"
        X-RateLimit-Remaining: "Requests remaining in window"
        X-RateLimit-Reset: "Unix timestamp when window resets"
        Retry-After: "Seconds to wait before retrying"
      resolution: |
        Implement exponential backoff. Check Retry-After header
        for the recommended wait time.
      code_example: |
        # Python: Automatic retry with backoff
        import time

        def api_call_with_retry(func, max_retries=3):
            for attempt in range(max_retries):
                response = func()
                if response.status_code != 429:
                    return response
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
            raise RateLimitError("Max retries exceeded")

Completeness:
  [ ] Every endpoint has description, parameters, and examples
  [ ] All error codes documented with resolution steps
  [ ] Authentication fully explained with code
  [ ] Rate limits and quotas documented
  [ ] Pagination strategy documented
  [ ] Webhook events and payloads documented
  [ ] Changelog tracks breaking and non-breaking changes

Clarity:
  [ ] Quickstart gets developer to "hello world" in < 5 minutes
  [ ] Code examples are copy-paste ready
  [ ] Examples show error handling, not just happy path
  [ ] Jargon is defined in a glossary
  [ ] Warnings and important notes are visually distinct

Developer Experience:
  [ ] Code examples in at least 3 languages
  [ ] Try-it-out console available for each endpoint
  [ ] Search works across all documentation
  [ ] Code examples include expected response
  [ ] Authentication tokens in examples use realistic format

Maintenance:
  [ ] OpenAPI spec is source of truth (docs auto-generated)
  [ ] Code examples tested in CI
  [ ] Docs versioned alongside API versions
  [ ] Feedback mechanism on each page
  [ ] Analytics tracking which pages have high bounce rate

# Api Documentation Writer Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]