Skip to main content

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

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.

Back to the full API Design roadmap