AI Rules for API Documentation

AI Builds APIs Nobody Can Use

AI generates APIs with: no endpoint documentation (consumers discover endpoints by reading source code), no field type descriptions (is 'status' a string or number? what values are valid?), no error documentation (what does a 400 mean for this endpoint?), no authentication instructions (which endpoints need auth? what format?), and no examples (what does a valid request look like?). The API exists but is effectively invisible — consumers spend more time guessing than building.

Modern API documentation is: spec-driven (OpenAPI 3.1 as the source of truth), example-rich (request + response for every endpoint, including error cases), error-cataloged (every error code mapped to cause and fix), auth-documented (clear instructions for obtaining and sending credentials), and auto-generated (SDK clients, Swagger UI, and Postman collections generated from the spec). AI generates none of these.

These rules cover: OpenAPI specification, request/response examples, error code catalogs, authentication documentation, and SDK generation from specs.

Rule 1: OpenAPI 3.1 as Source of Truth

The rule: 'Define your API using OpenAPI 3.1 specification. The spec is: the documentation (rendered as Swagger UI or Redoc), the contract (validated against incoming requests), the SDK generator input (openapi-generator creates client libraries), and the test fixture source (generate mock servers from the spec). One YAML/JSON file serves four purposes — documentation, validation, SDK generation, and testing.'

For spec-first vs code-first: 'Spec-first: write the OpenAPI spec before coding, then generate server stubs. Code-first: annotate your code with JSDoc/decorators, then generate the spec. Spec-first is better for: API-first companies, public APIs, and teams where API consumers influence the design. Code-first is better for: internal APIs, rapid prototyping, and teams where developers own both sides. Either way, the spec must exist and stay in sync.'

AI generates endpoints with no spec. Consumers reverse-engineer the API from: trial and error, reading source code, or asking the developer. An OpenAPI spec is: a Swagger UI page (interactive documentation), a Postman collection (importable test suite), and a client SDK (generated in any language). One file replaces hours of questions.

• OpenAPI 3.1 — JSON Schema compatible, webhooks support, latest standard
• One spec = documentation (Swagger UI) + validation + SDK generation + mock server
• Spec-first for public/external APIs — code-first for internal/rapid development
• Keep spec in version control — review spec changes in PRs like code changes
• Validate requests against spec in CI — catch contract violations before deploy

Rule 2: Request and Response Examples for Every Endpoint

The rule: 'Every endpoint needs at minimum: one success example (200/201 with complete response body), one validation error example (400 with field-level errors), one authentication error example (401 with the exact error format), and one not-found example (404). Include the full request (headers, query params, body) and full response (status, headers, body). Developers copy-paste examples — make them work.'

For example richness: 'Use realistic data, not: { "name": "string", "email": "string" }. Use: { "name": "Jane Chen", "email": "jane.chen@example.com", "role": "editor", "createdAt": "2026-03-27T14:30:00Z" }. Realistic examples: show the actual data shape (is createdAt ISO 8601?), demonstrate field formats (email has @, dates have timezone), and are directly usable in testing (paste into Postman).'

AI generates: an endpoint with no examples. The consumer makes a request, gets a 400, reads the error message (if there is one), adjusts, retries. Three round trips to discover the expected format. One example in the docs eliminates all three — the consumer gets it right on the first request.

Rule 3: Comprehensive Error Code Catalog

The rule: 'Document every error your API can return: the HTTP status code, a machine-readable error code (VALIDATION_ERROR, RATE_LIMITED, RESOURCE_NOT_FOUND), a human-readable message, the cause, and the fix. Publish this as an error catalog page in your docs. Every error response should include a link to the relevant catalog entry: { "error": { "code": "RATE_LIMITED", "message": "Too many requests", "docs": "https://docs.example.com/errors/rate-limited" } }.'

For structured error responses: 'Standardize error format across all endpoints: { "error": { "code": string, "message": string, "details": object | null, "docs": string } }. The code is machine-readable (clients switch on it). The message is human-readable (displayed to developers). The details carry context (which field failed validation, what the limit is). The docs link has the full explanation and fix.'

AI generates: res.status(400).json({ error: 'Bad request' }). Which field? What format? What should the client do? The developer guesses. A structured error with code, message, and docs URL turns a 30-minute debugging session into a 30-second documentation lookup.

Rule 4: Authentication and Authorization Documentation

The rule: 'Document the complete authentication flow: how to obtain credentials (API key, OAuth token), how to send them (Authorization: Bearer token, X-API-Key header), which endpoints require authentication (all? some?), what scopes/permissions are needed per endpoint, and what errors to expect (401 unauthorized, 403 forbidden — with the difference explained).'

For getting started: 'The first page of your API docs should be a Getting Started guide that takes the developer from zero to first successful API call in under 5 minutes: (1) sign up and get an API key, (2) copy this curl command, (3) see the response. If a developer cannot make a successful request within 5 minutes of reading your docs, your docs have failed. The curl command is the most important line in your documentation.'

AI generates APIs with no auth documentation. Developers discover auth requirements by: getting a 401 and guessing what header to send. One section — 'Authentication' — with a curl example, header format, and error responses, eliminates the most common source of API support questions.

Rule 5: SDK and Client Library Generation

The rule: 'Generate client SDKs from your OpenAPI spec — do not hand-write API clients for each language. Tools: openapi-generator (40+ languages), openapi-typescript (TypeScript types from spec), orval (React Query hooks from spec). Generated SDKs are: always in sync with the spec (regenerated on spec change), type-safe (TypeScript clients have full autocomplete), and consistent (same naming conventions across all languages).'

For TypeScript specifically: 'Use openapi-typescript to generate types, then openapi-fetch for a typed fetch wrapper: const { data, error } = await client.GET("/api/v1/users/{id}", { params: { path: { id: "123" } } }). Full autocomplete for paths, parameters, request bodies, and response types — all derived from the OpenAPI spec. Zero manual type definitions.'

AI generates: fetch('/api/users', { method: 'POST', body: JSON.stringify(data) }) with no types, no autocomplete, and no validation. A generated SDK gives you: typed paths, typed parameters, typed responses, and compile-time errors when the API changes. The spec is the contract; the SDK enforces it at compile time.

Complete API Documentation Rules Template

Consolidated rules for API documentation.

• OpenAPI 3.1 spec as source of truth — documentation, validation, SDK gen, mock server
• Examples for every endpoint: success, validation error, auth error, not found
• Realistic example data — not 'string' placeholders, actual values in correct formats
• Error catalog: HTTP status + error code + message + cause + fix + docs URL
• Structured error format: { error: { code, message, details, docs } } — consistent across all endpoints
• Authentication guide with curl example — first successful call in under 5 minutes
• Generated SDKs from OpenAPI spec — typed, always in sync, zero manual maintenance
• Spec in version control — review spec changes in PRs, validate in CI