Bad API documentation is a tax on every engineer who integrates with your service. It creates support tickets, delays integrations, and drives developers to competitor APIs. Good documentation is not just a reference — it is the fastest onboarding path, the clearest contract, and the best argument for adoption. In 2026 the tools to do this well are mature and mostly free.
What changed in 2026
- OpenAPI 3.1 closed the gap with JSON Schema. The spec is now a superset of JSON Schema 2020-12, so your validation schemas and your API spec can be the same document.
- AI code generation raised the documentation bar. Copilot and Cursor generate API clients from specs, which means a poorly typed spec generates broken code — correctness matters more than it did.
- Scalar and Mintlify replaced Swagger UI as the developer-portal of choice for most teams — better UX, interactive playgrounds, and easier theming.
- Contract testing with Schemathesis and Dredd made spec-as-truth enforceable in CI — if your implementation drifts from the spec, the build fails.
The documentation stack in 2026
| Layer |
Tool |
Purpose |
| Spec format |
OpenAPI 3.1 |
Machine-readable contract |
| Reference site |
Scalar / Mintlify / Redoc |
Human-readable interactive docs |
| SDK generation |
OpenAPI Generator / Stainless |
Client libraries from spec |
| Contract testing |
Schemathesis |
Verify implementation matches spec |
| Changelog |
Keep a Changelog format |
Track breaking and non-breaking changes |
Writing an OpenAPI 3.1 spec
openapi: "3.1.0"
info:
title: Orders API
version: "1.0.0"
paths:
/orders/{id}:
get:
operationId: getOrder
summary: Fetch a single order by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
example:
id: "a1b2c3d4-..."
status: "shipped"
total: 4999
"404":
$ref: "#/components/responses/NotFound"
Define reusable schemas in components/schemas, error responses in components/responses, and security schemes in components/securitySchemes.
What every endpoint doc needs
- Summary and description — one line for scanners, a paragraph for detail.
- All parameters — name, location (path/query/header), type, whether required, any enum values.
- Request body with a full working JSON example — not a schema diagram, an actual value.
- All response codes — at minimum 200, 400, 401, 403, 404, 422, 500.
- Response body with a full working example.
- Authentication — which scheme applies, how to get a token.
Authentication documentation
Authentication is the number-one integration blocker. Give it its own page:
## Authentication
All requests require a Bearer token in the Authorization header.
```http
Authorization: Bearer sk-live-abc123xyz
Tokens are scoped to an organization. Create them in the dashboard under
Settings → API Keys. Tokens never expire but can be revoked.
Error responses:
401 Unauthorized — token missing or malformed403 Forbidden — token valid but lacks permission for this resource
## Error reference
Document every error code your API returns — status code, error code string, description, and what the client should do:
| HTTP status | Error code | Meaning | Client action |
| --- | --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Request body failed schema validation | Fix the request; errors array has details |
| 401 | `UNAUTHORIZED` | Token missing or invalid | Re-authenticate |
| 429 | `RATE_LIMITED` | Too many requests | Retry after `Retry-After` header value |
| 422 | `BUSINESS_RULE_VIOLATION` | Structurally valid but breaks a business rule | Read the error message |
## How to pick your docs tooling
1. **Internal API, small team?** A well-maintained OpenAPI file plus Scalar UI served from your repo is enough.
2. **Public API with developer onboarding?** Mintlify or ReadMe — both support custom guides, API playground, and versioning.
3. **Need SDK generation?** Stainless (paid) or OpenAPI Generator (free) both produce idiomatic clients from the spec.
4. **Enterprise with strict security?** Redoc self-hosted — no third-party CDN dependencies.
5. **SDK-first API?** Generate the OpenAPI spec from your SDK types (Fern, TypeSpec) rather than writing it by hand.
## Common mistakes
**Spec and implementation drift.** The spec says one thing, the code does another. Contract testing (Schemathesis in CI) is the cure.
**Examples that do not work.** If you paste the example request and it returns a 422, your documentation is broken. Test every example.
**Missing pagination and filtering docs.** How to request page 2, how to filter by date range, what the cursor format is — these are the most common support questions.
**No changelog.** Developers need to know when things changed. A `CHANGELOG.md` in Keep a Changelog format, linked from the docs, covers this.
**Docs not versioned with the API.** v1 and v2 docs should be separately accessible, not overwritten on each release.
## What to skip
- **Long prose introductions** before showing a working request — get to the first API call within the first screen.
- **PDF documentation** for a REST API — it is immediately stale and unsearchable.
- **Swagger UI** if you have alternatives — Scalar and Redoc offer significantly better developer UX with minimal setup change.
## FAQ
**Should I write the spec first or generate it from code?**
Both work. Design-first (spec → implementation) produces cleaner contracts. Code-first (implementation → generated spec) ships faster but requires more cleanup. For public APIs, design-first pays off quickly.
**How do I keep examples up to date?**
Use Schemathesis or Dredd in CI to run the example requests against a running server and assert the responses match the documented schema.
**Do I need a developer portal if my API is internal?**
Even for internal APIs, a rendered reference reduces onboarding time significantly. A static Redoc or Scalar site deployed alongside the service is a one-hour setup.
**How do I document webhooks?**
Document them as a separate section: the event type, the payload schema (with a full example), delivery guarantees, retry policy, and how to verify the signature.
## Where to go next
See [How to version an API in 2026](/blog/how-to-version-an-api-2026), [What is REST APIs in 2026](/blog/what-is-rest-apis-2026), and [How to handle errors gracefully in 2026](/blog/how-to-handle-errors-gracefully-2026).