API Doc Structure
| Item | Description |
|---|
1. Overview | What the API does, base URL, authentication method, rate limits, API version. 2-minute read. |
2. Authentication | How to get API keys, OAuth flow, token format, environment variables for storing keys. |
3. Quickstart | Curl command that works immediately after copy-paste. 'Your first API call in 30 seconds.' |
4. Concepts | Key domain concepts: 'In our API, a Workspace contains Projects, which contain Tasks.' |
5. Endpoints | Method, path, description, parameters, request example, response example, error responses. |
6. Guides | Common workflows: 'How to upload a file', 'How to set up webhooks', pagination, error handling. |
7. SDKs / Libraries | Installation, instantiation, key methods with examples. Link to source repos. |
Endpoint Documentation Pattern
| Item | Description |
|---|
Method + Path | `GET /api/v1/users/{id}` — HTTP method, full path, path parameters in braces |
Description | 1-2 sentences describing what it does. 'Returns a user object by ID.' |
Path Parameters | Table: Name, Type, Required, Description. `id: string, required, The user UUID` |
Query Parameters | Table: Name, Type, Required, Default, Description. `limit: integer, optional, 20, Max results` |
Request Body | JSON example with all possible fields. Indicate required vs optional. Include field descriptions. |
Response | JSON example for 200, plus common error responses (400, 401, 404, 429, 500). |
OpenAPI / Swagger Tips
| Item | Description |
|---|
Use OpenAPI 3.1 | Latest version. Better JSON Schema support, webhook support, better examples. |
description Fields | Every endpoint, parameter, and schema property needs a description. Auto-generated docs use these. |
examples > example | The `examples` field (plural) supports multiple named examples. Better than single `example`. |
$ref for Reuse | Extract common schemas: `$ref: '#/components/schemas/User'`. Don't duplicate schema definitions. |
Redoc / Swagger UI | Render OpenAPI specs as beautiful docs. Redoc = cleaner, Swagger UI = interactive 'Try it'. |
Validation | Use spectral (Stoplight) to lint your OpenAPI spec. Catch missing descriptions, inconsistent naming. |
Developer Experience
| Item | Description |
|---|
Copy-Paste Ready | Every code example should run without modification. Use placeholder values that look real. |
Error Messages | Return actionable errors: 'API key invalid. Get one at https://...' not 'Unauthorized.' |
Changelog | Public changelog with dates. Breaking changes in BOLD at top. Migration guides for version bumps. |
Rate Limit Headers | Return X-RateLimit-Remaining headers. Developer can self-police instead of hitting 429s. |
SDK Generation | Use openapi-generator to create SDKs in 20+ languages from your OpenAPI spec. Keep them in sync. |
Pro Tip: The 'Getting Started' section is the most important page in your API docs. A developer should make their first successful API call within 5 minutes. If they can't, you've already lost 50% of potential users.