API Documentation

API documentation is the first thing a developer sees when evaluating your API. Before they read a single line of your source code, before they write a single line of integration code, they read your docs. Bad documentation turns away developers who would otherwise adopt your API. Good documentation is a competitive advantage.

The standard for API documentation has been set by Stripe, Twilio, and GitHub. Developers now expect interactive documentation, code examples in multiple languages, and a quickstart guide that gets them to a successful API call in under five minutes.

OpenAPI & Swagger

OpenAPI (formerly Swagger) is the standard specification format for REST API documentation. It describes your endpoints, request/response schemas, authentication methods, and error formats in a machine-readable YAML or JSON file.

{
  "openapi": "3.1.0",
  "info": {
    "title": "User Service API",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/users/{id}": {
      "get": {
        "summary": "Get user by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "string"},
                    "name": {"type": "string"},
                    "email": {"type": "string", "format": "email"}
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    }
  }
}

This specification drives everything: documentation generation, SDK generation, contract testing, and API mocking. The spec is the single source of truth.

Auto-Generated vs Hand-Written

Auto-generated documentation extracts the OpenAPI spec from your code annotations or route definitions. The spec is always in sync with the implementation because it comes from the implementation.

The risk: auto-generated docs tend to be dry and lack context. They describe what the API does but not why or how to use it effectively.

Hand-written documentation is authored separately from the code. It includes tutorials, guides, and contextual explanations that auto-generated docs lack.

The risk: hand-written docs drift from the implementation. The endpoint changes but the docs do not get updated.

The best approach combines both: auto-generate the reference documentation from the OpenAPI spec, and hand-write the guides, tutorials, and conceptual explanations.

Interactive Documentation

Swagger UI

Swagger UI renders your OpenAPI spec as an interactive web page. Developers can read endpoint descriptions, see request/response schemas, and make real API calls from the browser.

Swagger UI features:
  - Endpoint list grouped by tag
  - Request parameter forms
  - "Try it out" button for live API calls
  - Response body with syntax highlighting
  - Authentication configuration panel

The "Try it out" feature is powerful for onboarding. A developer can make their first API call without writing any code, directly from the documentation page.

Redoc

Redoc is an alternative OpenAPI renderer with a three-panel layout: navigation on the left, documentation in the center, and code examples on the right. It produces cleaner, more readable documentation than Swagger UI's default layout.

Redoc layout:
  Left panel:  Table of contents with all endpoints
  Center panel: Endpoint description, parameters, schemas
  Right panel:  Request/response examples, code snippets

Redoc is better for reading. Swagger UI is better for interacting. Many teams use Redoc for the public documentation site and Swagger UI for internal development.

Stoplight & ReadMe

Hosted documentation platforms that combine OpenAPI rendering with hand-written guides, changelogs, and analytics. They track which documentation pages developers visit most, which code examples they copy, and where they drop off.

Code Examples

Code examples are the most-used part of API documentation. Developers copy-paste examples and modify them. If your examples are wrong, incomplete, or only available in one language, developers struggle.

Multiple Languages

Provide examples in the languages your consumers use:

curl:
  curl https://api.example.com/v1/users \
    -H "Authorization: Bearer sk_live_abc123" \
    -H "Content-Type: application/json" \
    -d '{"name": "Jane Doe", "email": "jane@example.com"}'

Python:
  import requests
  
  response = requests.post(
      "https://api.example.com/v1/users",
      headers={"Authorization": "Bearer sk_live_abc123"},
      json={"name": "Jane Doe", "email": "jane@example.com"}
  )
  user = response.json()

JavaScript:
  const response = await fetch("https://api.example.com/v1/users", {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_abc123",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({name: "Jane Doe", email: "jane@example.com"})
  });
  const user = await response.json();

Stripe provides examples in curl, Ruby, Python, PHP, Java, Node.js, Go, and .NET for every endpoint. This breadth is part of why Stripe's documentation is considered the best in the industry.

Complete, Runnable Examples

Every example should be copy-pasteable and runnable. Do not omit imports, do not use pseudo-code, and do not assume the developer knows how to set up authentication.

Bad example:

// Make a request to create a user
createUser({name: "Jane"})

Good example:

const response = await fetch("https://api.example.com/v1/users", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Jane Doe",
    email: "jane@example.com"
  })
});

const user = await response.json();
console.log(user.id); // "user_abc123"

Include the expected response so developers know what success looks like:

{
  "id": "user_abc123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "created_at": "2025-01-15T10:30:00Z"
}

Essential Documentation Sections

Authentication Guide

The first thing a developer needs. How do I get an API key? Where do I put it? What scopes do I need?

## Authentication

All API requests require a Bearer token in the Authorization header.

1. Sign up at dashboard.example.com
2. Navigate to Settings → API Keys
3. Copy your secret key (starts with sk_live_)
4. Include it in every request:

   Authorization: Bearer sk_live_your_key_here

Test keys (sk_test_) work in sandbox mode.
Live keys (sk_live_) work in production.

Quickstart Guide

A step-by-step tutorial that takes the developer from zero to a successful API call. Target: under 5 minutes.

## Quickstart

1. Get your API key from dashboard.example.com
2. Make your first request:

   curl https://api.example.com/v1/users \
     -H "Authorization: Bearer sk_test_abc123"

3. You should see a list of users in the response.
4. Create your first user:

   curl https://api.example.com/v1/users \
     -H "Authorization: Bearer sk_test_abc123" \
     -H "Content-Type: application/json" \
     -d '{"name": "Test User", "email": "test@example.com"}'

5. You should get back a 201 response with the new user.

Changelog

Every API change, documented with the date, what changed, and whether it is breaking:

## Changelog

### 2025-01-15
- Added `phone` field to User resource (non-breaking)
- Added GET /v1/users/{id}/orders endpoint (non-breaking)

### 2024-12-01
- BREAKING: Renamed `email_address` to `email` in User resource
  Migration guide: docs.example.com/migration/email-field
- Deprecated GET /v1/users/search (use query params on GET /v1/users)
  Sunset date: 2025-06-01

Error Reference

A complete catalog of all error codes, as described in the error codes topic. Link from the main documentation to the error reference.

The Best API Documentation

Stripe

Three-panel layout: navigation, explanation, and code examples side by side. Every endpoint has examples in 8+ languages. Interactive testing with test-mode API keys. Error code catalog with resolution steps. Versioned docs matching your account's API version.

Documentation CI pipeline:
  1. Extract code examples from documentation
  2. Run each example against a test API
  3. Verify the response matches the documented output
  4. Fail the build if any example is broken

Tools like Docusaurus, ReadMe, and custom scripts can extract code blocks from documentation and execute them. This ensures that every code example in your docs actually works.

Common Pitfalls

Documentation as an afterthought — writing docs after launch, under time pressure, with incomplete information. Documentation should ship with the API, not after it.
Only reference docs — providing endpoint descriptions without guides, tutorials, or conceptual explanations. Reference docs tell you what. Guides tell you how and why.
Single-language examples — providing examples only in curl or only in one programming language. Developers use many languages; cover the most common ones.
Stale examples — code examples that no longer work because the API changed. Automate documentation testing to catch this.
No authentication guide — assuming developers know how to authenticate. The auth guide is the first thing they need.
No quickstart — forcing developers to read the entire documentation before making their first API call. The quickstart should take under 5 minutes.
No changelog — making changes without documenting them. Developers need to know what changed and when.

Key Takeaways

OpenAPI/Swagger is the standard for REST API documentation. Use it as the source of truth for reference docs, and hand-write guides and tutorials alongside it.
Interactive documentation (Swagger UI, Redoc) lets developers make API calls from the browser. This accelerates onboarding and reduces time to first successful call.
Provide code examples in multiple languages. Every example should be complete, runnable, and copy-pasteable.
Essential sections: authentication guide, quickstart guide, endpoint reference, error catalog, and changelog. Missing any of these frustrates developers.
Stripe, Twilio, and GitHub set the documentation standard. Study their docs before designing your own.
Documentation is the first thing developers see and the last thing teams invest in. Treat it as a product with its own quality bar and testing pipeline.