Writing API Documentation
Good API documentation is the difference between an API people use and an API nobody uses. Developers can't use an API they don't understand. Poor documentation costs as much time as it saves.
OpenAPI/Swagger: The Standard
OpenAPI (formerly Swagger) is the standard specification for REST APIs. A JSON or YAML file describes every endpoint: URL, method, parameters, request body, response structure, error codes.
OpenAPI documents are machine-readable. Tools generate interactive documentation, client libraries, even server stubs. The specification is always in sync with the API.
Auto-Generating Documentation
FastAPI (Python) generates OpenAPI docs automatically from type hints. Write a function with type annotations, FastAPI generates the specification and interactive docs.
NestJS (Node.js) uses decorators to generate OpenAPI. Swagger module parses decorators and builds the spec. No manual documentation needed.
This is powerful. Your specification is always in sync with code. If you change a parameter type, the spec updates automatically.
What Good Documentation Includes
Endpoint descriptions: what does this endpoint do? POST /api/users creates a new user.
Parameters: what inputs are required or optional? User ID is required, filters are optional.
Request body: what structure is expected? JSON object with name, email, password fields.
Response structure: what does a successful response look like? User object with id, name, email, created_at.
Error codes: what can go wrong? 400 Bad Request if email is invalid. 401 Unauthorized if not authenticated. 500 Server Error.
Authentication: how do you authenticate? Bearer token in Authorization header? API key? OAuth?
Examples: sample requests and responses. This is invaluable for developers trying to understand how to use the endpoint.
What Bad Documentation Looks Like
Just endpoint URLs with no explanation. Swagger showing parameters with no context. Example responses with no indication of which fields are required, which are optional. Error documentation missing—no explanation of when each error occurs.
Outdated documentation inconsistent with actual API. Endpoints described that don't exist. Parameters documented that no longer exist.
Postman Collections as Documentation
Postman collections are shareable. Export your collection as JSON. Developers import it and have all your endpoints ready to test. This supplements formal documentation.
Collections can include examples, pre-request scripts, and tests. They're practical documentation.
Documentation for Internal APIs
Even internal APIs benefit from documentation. New team members joining need to understand what endpoints are available. Your future self, months later, needs reminders.
Generate documentation from OpenAPI specs. Or write manually. Just document it.
Versioning Documentation Alongside the API
When you have multiple API versions, documentation for each must be available. /api/v1/users and /api/v2/users have different structures. Documentation must reflect this.
Version control docs alongside code. When you commit a new API version, commit documentation for it.
Changelog and Deprecations
Document what changed between versions. New endpoints, renamed fields, removed endpoints. A changelog helps developers understand upgrades.
Document deprecations clearly. If you're retiring an endpoint, announce it in the docs. When will it be removed? What should developers use instead?
Interactive Documentation
Swagger UI and ReDoc generate interactive documentation from OpenAPI specs. Developers can try endpoints in the browser. "Try it out" sends real requests to the API.
This is powerful for exploration and learning. Developers see the request, response, and can experiment.
Documentation as a Learning Tool
Documentation is often the first thing developers read about your API. It teaches them your design philosophy, conventions, error handling. Make it good.
Clear documentation reduces support burden. Fewer "How do I...?" questions if the docs answer them.