loom-api-documentation

name	loom-api-documentation
description	Document REST APIs with OpenAPI/Swagger specifications, endpoint references, authentication flows, error handling, and SDK guides. Use for API reference docs, Swagger specs, interactive explorers, and client library documentation.
triggers	["api docs","openapi","swagger","endpoint documentation","rest api","api reference","sdk documentation","api specification","document api","api endpoints","request response examples","schema documentation","openapi 3.1","redoc","stoplight","postman collection","api explorer","interactive docs","api contract","api schema","swagger ui","authentication flows","rate limits"]

API Documentation

Overview

Comprehensive API documentation skill covering OpenAPI/Swagger specifications, endpoint documentation, authentication flows, error handling, versioning strategies, and SDK/client documentation. Combines technical precision with clear, user-friendly writing to create documentation that developers can actually use.

Instructions

1. Understand the API First

• Review all endpoints and their purposes
• Identify authentication mechanisms
• Understand request/response schemas
• Note error conditions and edge cases
• Check existing API patterns for consistency

2. Documentation Components

Every API should document:

1. Authentication: How to authenticate
2. Base URL: Environment-specific URLs
3. Endpoints: All available operations
4. Schemas: Request/response models
5. Errors: Error codes and handling
6. Rate limits: Throttling policies
7. Versioning: How versions work

Best Practices

Technical Accuracy

• Use consistent terminology throughout
• Keep schemas DRY with $ref
• Document all possible response codes
• Validate examples against schema
• Include proper JSON Schema constraints

Clarity and Usability (from technical-writer expertise)

• Write for the developer audience: assume technical competence, skip patronizing explanations
• Lead with practical examples: show before explaining
• Use active voice and direct language
• Provide working curl examples for every endpoint
• Explain authentication with complete, copy-paste examples
• Document rate limits with concrete numbers and headers
• Surface common error scenarios prominently
• Include troubleshooting tips for frequent issues

Interactive Documentation

• Design for auto-generated docs (Redoc, Swagger UI, Stoplight)
• Use operationId for stable client generation
• Tag endpoints logically for navigation
• Write descriptions that render well in both markdown and UI tools
• Include multiple request/response examples for different scenarios

OpenAPI 3.1 Key Features

Full JSON Schema Support

• Use JSON Schema 2020-12 vocabulary
• Support const, if/then/else, dependentSchemas
• Native oneOf/anyOf/allOf with discriminators

Example Handling

• Single example: use example property
• Multiple examples: use examples object with named scenarios
• Examples in both schema definitions AND operation level

Webhooks Documentation

webhooks:
  userCreated:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserEvent"

Content Negotiation

content:
  application/json:
    schema: { ... }
  application/xml:
    schema: { ... }
  text/csv:
    schema:
      type: string

Security Schemes

• OAuth2 with multiple flows
• OpenID Connect Discovery
• Mutual TLS
• Custom security schemes with extensions

Examples

OpenAPI/Swagger Specification

openapi: 3.1.0
info:
  title: User Management API
  description: |
    API for managing users and their profiles.

    ## Authentication
    All endpoints require Bearer token authentication.
    Obtain a token via POST /auth/login.

    ## Rate Limits
    - Standard: 100 requests/minute
    - Authenticated: 1000 requests/minute
  version: 2.0.0
  contact:
    name: API Support
    email: [e-mail]
    url: https://developer.example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v2
    description: Production
  -  
     
    
      


    
       
    
       


    []


  
    
         
              
      
         
      
          
          
          
           
              
          
             
             [, , ]
          
           
               
          
             
             
      
        
            
          
            
              
                 
              
                
                    
                     
                     
                     
                     
                
                   
                   
                   
                   
        
           
        
           

    
          
           
       
      
         
      
         
        
          
            
               
            
              
                   
                
                   
                   
                   
              
                    
                
                   
                   
                   
                   
      
        
             
          
            
              
                 
        
           
        
                
          
            
              
                 
              
                
                   
                   

  
    
          
              
       
      
         
      
          
      
        
            
          
            
              
                 
        
           

    
        
              
       
      
         
      
          
      
         
        
          
            
               
      
        
             
          
            
              
                 
        
           
        
           

    
        
           
       
      
         
      
          
      
        
             
        
           


  
    
       
       
       
       
    
       
       
       
           

  
    
       
       
       
         
      
         
         
       

    
       
       
         
      
         
         
         

    
       
       
           
      
         
         
         
         

  
    
       
      
         
         
         
         
         
      
        
           
            
           
        
           
           
             
           
        
           
             
            
        
           
           [, , ]
            
        
           
           [, , ]
           
        
           
           
             
        
           
           
             

    
       
      
         
         
         
      
        
           
           
        
           
           
           
        
           
           
           
                  
        
           
           [, , ]
           

    
       
       
      
        
           
           
           
        
           
           [, ]

    
       
      
        
           

    
       
      
        
           
          
             
        
           

    
       
      
        
           
        
           
        
           
        
           

    
       
      
        
           
          
            
               
                 
            
               
                 
            
               
              
                 
                
                  
                     
                  
                     

  
    
         
      
        
          
             
          
            
               
               
              
                  
                   

    
        
      
        
          
             
          
            
               
               

    
         
      
        
          
             
          
            
               
               

    
         
      
        
          
             
              
        
          
             
            
        
          
             
               
      
        
          
             
          
            
               
               

Endpoint Documentation (Markdown)

## Create User

Create a new user account in the system.

**Endpoint:** `POST /users`

**Authentication:** Required (Bearer token)

### Request

#### Headers

| Header        | Required | Description                           |
| ------------- | -------- | ------------------------------------- |
| Authorization | Yes      | Bearer token                          |
| Content-Type  | Yes      | `application/json`                    |
| X-Request-Id  | No       | Unique request identifier for tracing |

#### Body Parameters

| Parameter | Type   | Required | Description                                                                     |
| --------- | ------ | -------- | ------------------------------------------------------------------------------- |
| email     | string | Yes      | Valid email address                                                             |
| name      | string | Yes      | Full name (2-100 characters)                                                    |
| password  | string | Yes      | Password (min 8 chars, must include uppercase, lowercase, number, special char) |
| role      | string | No       | User role: `user`, `admin`, `moderator`. Default: `user`                        |

#### Example Request

\`\`\`bash
curl -X POST https://api.example.com/v2/users \
 -H "Authorization: Bearer eyJhbG..." \
 -H "Content-Type: application/json" \
 -d '{
"email": "[e-mail]",
"name": "Jane Smith",
"password": "SecureP@ss123"
}'
\`\`\`

### Response

#### Success Response (201 Created)

\`\`\`json
{
"data": {
"id": "usr_abc123",
"email": "[e-mail]",
"name": "Jane Smith",
"status": "pending",
"role": "user",
"createdAt": "2024-01-15T10:30:00Z"
}
}
\`\`\`

#### Error Responses

| Status | Code             | Description              |
| ------ | ---------------- | ------------------------ |
| 400    | VALIDATION_ERROR | Invalid request body     |
| 401    | UNAUTHORIZED     | Missing or invalid token |
| 409    | USER_EXISTS      | Email already registered |
| 429    | RATE_LIMITED     | Too many requests        |

**400 Bad Request:**
\`\`\`json
{
"error": {
"code": "VALIDATION

Authentication Documentation

# Authentication

## Overview

The API supports two authentication methods:

1. **Bearer Token (JWT)** - For user-facing applications
2. **API Key** - For server-to-server integrations

## Bearer Token Authentication

### Obtaining a Token

\`\`\`bash
POST /auth/login
Content-Type: application/json

{
"email": "[e-mail]",
"password": "your-password"
}
\`\`\`

**Response:**
\`\`\`json
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
"expiresIn": 3600,
"tokenType": "Bearer"
}
\`\`\`

### Using the Token

Include the token in the Authorization header:

\`\`\`
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
\`\`\`

### Token Lifecycle

| Token         | Lifetime | Usage                   |
| ------------- | -------- | ----------------------- |
| Access Token  | 1 hour   | API requests            |
| Refresh Token | 30 days  | Obtain new access token |

### Refreshing Tokens

\`\`\`bash
POST /auth/refresh
Content-Type: application/json

{
"refreshToken": "dGhpcyBpcyBhIHJlZnJl..."
}
\`\`\`

## API Key Authentication

For server-to-server integrations, use API key authentication.

### Creating an API Key

1. Go to Dashboard > Settings > API Keys
2. Click "Create New Key"
3. Select permissions and expiration
4. Copy and securely store the key

### Using the API Key

Include in the `X-API-Key` header:

\`\`\`
X-API-Key: sk_live_abc123...
\`\`\`

### API Key Best Practices

- Never expose keys in client-side code
- Rotate keys regularly (every 90 days)
- Use separate keys for each environment
 Apply minimum required permissions

Error Response Documentation

# Error Handling

## Error Response Format

All errors follow a consistent format:

\`\`\`json
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description",
"details": [
{
"field": "fieldName",
"message": "Field-specific error"
}
],
"requestId": "req_abc123"
}
}
\`\`\`

## HTTP Status Codes

| Status | Meaning           | When Used                               |
| ------ | ----------------- | --------------------------------------- |
| 200    | OK                | Successful GET, PUT, PATCH              |
| 201    | Created           | Successful POST creating resource       |
| 204    | No Content        | Successful DELETE                       |
| 400    | Bad Request       | Invalid request syntax or parameters    |
| 401    | Unauthorized      | Missing or invalid authentication       |
| 403    | Forbidden         | Valid auth but insufficient permissions |
| 404    | Not Found         | Resource doesn't exist                  |
| 409    | Conflict          | Resource state conflict                 |
| 422    | Unprocessable     | Valid syntax but semantic errors        |
| 429    | Too Many Requests | Rate limit exceeded                     |
| 500    | Internal Error    | Server-side error                       |

## Common Error Codes

### Authentication Errors

| Code               | HTTP Status | Description            | Resolution                   |
| ------------------ | ----------- | ---------------------- | ---------------------------- |
| UNAUTHORIZED       | 401         | No token provided      | Include Authorization header |
| TOKEN_EXPIRED      | 401         | Token has expired      | Refresh your access token    |
| TOKEN_INVALID      | 401         | Token is malformed     | Obtain a new token           |
| INSUFFICIENT_SCOPE | 403         | Token lacks permission | Request with proper scopes   |

### Validation Errors

| Code             | HTTP Status | Description               | Resolution                          |
| ---------------- | ----------- | ------------------------- | ----------------------------------- |
| VALIDATION_ERROR | 400         | Request failed validation | Check `details` for specific fields |
| INVALID_JSON     | 400         | Malformed JSON body       | Verify JSON syntax                  |
| MISSING_FIELD    | 400         | Required field missing    | Include all required fields         |

### Resource Errors

| Code            | HTTP Status | Description            | Resolution             |
| --------------- | ----------- | ---------------------- | ---------------------- |
| NOTEXISTS  | 409         | Duplicate resource     | Use unique identifiers |
| RESOURCEERROR') {
const fieldErrors = error.body.error.details;
displayFieldErrors(fieldErrors);
}
}
\\`

Versioning Documentation

# API Versioning

## Version Format

The API uses URL path versioning:

\`\`\`
https://api.example.com/v{major}/resource
\`\`\`

Current version: **v2**

## Supported Versions

| Version | Status     | Sunset Date |
| ------- | ---------- | ----------- |
| v2      | Current    | -           |
| v1      | Deprecated | 2024-12-31  |

## Version Lifecycle

1. **Current**: Actively developed and supported
2. **Deprecated**: Supported but no new features
3. **Sunset**: Read-only access for 90 days
4. **Retired**: No longer accessible

## Breaking vs Non-Breaking Changes

### Non-Breaking (No version bump)

- Adding new endpoints
- Adding optional parameters
- Adding new response fields
- Adding new enum values

### Breaking (Major version bump)

- Removing endpoints
- Removing or renaming fields
- Changing field types
- Changing authentication method
- Changing error format

## Migration Guide: v1 to v2

### Authentication Change

**v1:** API Key in query parameter
\`\`\`
GET /v1/users?api_key=abc123
\`\`\`

**v2:** Bearer token in header
\`\`\`
GET /v2/users
Authorization: Bearer eyJhbG...
\`\`\`

### Response Format Change

**v1:** Flat response
\`\`\`json
{
"id": "123",
"name": "John"
}
\`\`\`

**v2:** Wrapped response
\`\`\`json
{
"data": {
"id": "usr_123",
"name": "John"
}
}
\`\`\`

SDK Documentation

# JavaScript SDK

## Installation

\`\`\`bash
npm install @example/api-client
\`\`\`

## Quick Start

\`\`\`javascript
import { ApiClient } from '@example/api-client';

const client = new ApiClient({
apiKey: process.env.API_KEY,
environment: 'production' // or 'sandbox'
});

// Create a user
const user = await client.users.create({
email: '[e-mail]',
name: 'Jane Smith'
});

console.log(user.id); // usr_abc123
\`\`\`

## Configuration

\`\`\`javascript
const client = new ApiClient({
// Required
apiKey: 'sk*live*...',

// Optional
environment: 'production', // 'production' | 'sandbox'
timeout: 30000, // Request timeout in ms
retries: 3, // Auto-retry failed requests
logger: console, // Custom logger
});
\`\`\`

## Resources

### Users

\`\`\`javascript
// List users with pagination
const { data, pagination } = await client.users.list({
page: 1,
limit: 20,
status: 'active'
});

// Get single user
const user = await client.users.get('usr_123');

// Create user
const newUser = await client.users.create({
email: '[e-mail]',
name: 'New User'
});

// Update user
const updated = await client.users.update('usr_123', {
name: 'Updated Name'
});

// Delete user
await client.users.delete('usr_123');
\`\`\`

## Error Handling

\`\`\`javascript
import { ApiError, ValidationError, RateLimitError } from '@example/api-client';

try {
await client.users.create({ email: 'invalid' });
} catch (error) {
if (error instanceof ValidationError) {
console.log(error.details); // Field-level errors
} else if (error instanceof RateLimitError) {
console.log(`Retry after ${error.retryAfter} seconds`);
} else if (error instanceof ApiError) {
console.log(error.code, error.message);
}
}
\`\`\`

## TypeScript Support

The SDK includes full TypeScript definitions:

\`\`\`typescript
import { ApiClient, User, CreateUserParams } from '@example/api-client';

const params: CreateUserParams = {
email: '[e-mail]',
name: 'Typed User'
};

const user: User = await client.users.create(params);
\`\`\`

Documentation Tooling

Interactive Documentation Generators

Redoc - Clean, three-panel layout with search

npx @redocly/cli build-docs openapi.yaml --output docs.html

Swagger UI - Try-it-out functionality, widely recognized

docker run -p 80:8080 -e SWAGGER_JSON=/api/openapi.yaml -v $(pwd):/api swaggerapi/swagger-ui

Stoplight Elements - Embeddable web components

<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<elements-api apiDescriptionUrl="./openapi.yaml" router="hash" />

Validation and Linting

Redocly CLI - Lint OpenAPI specs

npx @redocly/cli lint openapi.yaml
npx @redocly/cli bundle openapi.yaml --output bundled.yaml

Spectral - Flexible linting with custom rules

spectral lint openapi.yaml --ruleset .spectral.yaml

Client Generation

OpenAPI Generator - Multi-language client/server generation

openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client

Postman Collection Export

npm install -g openapi-to-postmanv2
openapi2postmanv2 -s openapi.yaml -o collection.json

Testing and Mocking

Prism - Mock server from OpenAPI spec

prism mock openapi.yaml
# Returns example responses from your spec

Dredd - Test API against OpenAPI contract

dredd openapi.yaml http://localhost:3000

Documentation Patterns

Progressive Disclosure

Structure docs from quick start to advanced topics:

1. Authentication quick start (single example)
2. Common use cases (recipes)
3. Complete endpoint reference
4. Advanced topics (webhooks, pagination strategies)

Code Examples Strategy

• Provide examples in multiple languages (curl, JavaScript, Python, Go)
• Use realistic data (not foo/bar)
• Show complete working examples, not fragments
• Include error handling in examples

API Explorer Integration

Include "Try It" functionality:

• Pre-fill authentication from environment
• Provide example payloads
• Show actual requests/responses
• Support environment switching (sandbox/production)

Versioning Communication

• Announce deprecations 6+ months in advance
• Provide migration guides with side-by-side comparisons
• Include deprecation headers in API responses
• Maintain changelog with breaking/non-breaking labels