Documentation for API Designs
API documentation is the written and machine-readable description of an API, centred on the OpenAPI specification, a YAML or JSON file that lists paths, parameters, schemas and responses. It feeds reference pages, mock servers and generated client code, and it works best when guides and examples sit beside it.
Stage: Lifecycle · Part of the API Design roadmap · Last reviewed 19 November 2026
What to learn in Documentation
- Write an OpenAPI 3 document with paths, schemas, parameters and responses
- Reuse components and $ref to avoid repeating schemas
- Add realistic examples and describe every error response
- Generate reference docs and a mock server from the specification
- Write a getting-started guide that gets a developer to a first successful call
Documentation interview questions
What is the difference between OpenAPI and Swagger?
OpenAPI is the specification format for describing HTTP APIs, previously called the Swagger Specification. Swagger now refers to a family of tools, such as Swagger UI and Swagger Editor, that read OpenAPI files to render documentation or help write them.
What is design-first API development?
In a design-first approach you write and review the OpenAPI contract before any code, so teams agree on behaviour early. Frontend, backend and test teams can then work in parallel using mocks and generated stubs. Code-first instead generates the spec from implementation and risks drift.
Where Documentation fits in the API Design roadmap
Documentation belongs to the Lifecycle stage (intermediate level). Evolve safely.
Other units in this stage
Back to the full API Design roadmap