OpenAPI and the API Documentation Tooling Landscape

Beginner · 44 min

What an OpenAPI document describes, the tradeoff between writing the spec first and generating it from code, and the categories of tool that sit on top of it.

Sriniously · 44 min

OpenAPI and the API Documentation Tooling Landscape

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by SriniouslyReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • An OpenAPI document is a contract, not prose documentation: `paths` list the operations, each operation's parameters and request body describe the inputs, and `responses` plus the reusable `components.schemas` objects describe every possible output — all of it machine-readable, which is what everything else in this group builds on.
  • Spec-first means the YAML/JSON file is the source of truth and code, docs, mocks, and client SDKs all get generated or validated against it; code-first means the spec gets generated from annotations in the implementation after the fact — the real tradeoff is upfront design discipline versus the risk of the generated spec quietly drifting from what the code actually does.
  • Documentation tooling splits into three categories solving different problems, not one "best" product: renderers that turn a spec into browsable docs (Swagger UI, Redoc, Scalar), exploration/collection tools built for manually poking at an API and sharing requests with a team (Postman, Insomnia), and hosted developer-portal platforms that combine rendering, versioning, and onboarding content for external consumers (Readme.com, Stoplight).
  • A beautifully rendered doc generated from an inaccurate spec is worse than a plain doc generated from an accurate one — the spec's correctness is the actual asset; the renderer is a coat of paint on top of it.
  • The spec you write here isn't just for documentation — `contract-testing-for-apis` validates real responses against it and `mocking-and-virtualizing-apis` generates a working mock server directly from it, so errors in this file propagate forward into every later stage of this group.

What an OpenAPI document actually describes

rest-resource-modeling-and-uri-design covers how to design the resources and URIs an API exposes. OpenAPI is how you write that design down in a form a machine can read, not just a human. The document has a handful of load-bearing sections: paths lists every route and, under each one, every HTTP operation (get, post, patch, …) that route supports; each operation declares its parameters (path, query, header) and, where relevant, a requestBody, both pointing at schemas that describe their shape; and responses enumerates every status code the operation can return, each one again pointing at a schema for its body.

The piece that makes a spec maintainable rather than a wall of repetition is components. Instead of inlining the shape of a User or an Order object inside every operation that touches one, you define it once under components.schemas and reference it everywhere with $ref. That’s not a stylistic nicety — it’s the difference between one place to fix a field and a dozen copies that quietly drift apart. The same pattern applies to reusable parameters, response shapes, and security schemes. A spec built this way reads less like documentation and more like a type system for your API’s wire format, which is exactly what it is: everything downstream — a generated client, a mock server, a contract-testing tool — is reading these same definitions, not a paragraph of prose someone wrote and never updated.

Spec-first vs code-first

There are two honest ways to produce this file, and neither is strictly correct. Spec-first (also called design-first or contract-first) means you write the OpenAPI document before any implementation exists. The spec becomes the artifact teams negotiate over — a frontend team can start building against it, a mock server can serve from it, and the backend team implements to match it. The cost is upfront: someone has to sit down and design the contract before a line of handler code exists, and if the team skips real review at that stage, you’ve just moved the design mistakes earlier instead of preventing them.

Code-first means you write the implementation first, annotate it (decorators in a framework like FastAPI or NestJS, comments a tool like swaggo parses, attributes in ASP.NET), and generate the spec from those annotations. This feels faster day to day — you’re writing real code immediately — but it inverts where the truth lives. The spec is now a derived artifact, and derived artifacts drift: a handler that changes its validation logic without updating its annotation produces a spec that’s quietly wrong, and nothing forces anyone to notice until a consumer hits the mismatch in production. Code-first works well for a small team iterating fast on an internal API; spec-first earns its upfront cost once external consumers, multiple teams, or a mobile client building in parallel are in the picture, because the contract has to be stable and agreed before everyone can work against it at once.

Whichever direction you build the spec, contract-testing-for-apis, the next lesson in this group, is what actually keeps it honest once code starts changing underneath it.

The tooling landscape, as categories

Don’t evaluate “API documentation tools” as one bucket — they split into three categories that solve different problems, and a real team typically uses more than one at the same time.

Renderers turn a spec into browsable, readable documentation. Swagger UI is the default — free, embeds directly, and lets a reader fire requests at the live API from the page itself. Redoc renders the same spec as cleaner, more document-like static pages, better suited to a published reference than an interactive playground. Scalar is a newer entrant doing both, with a more modern UI. All three take the same input (your OpenAPI file) and differ only in how they present it — swapping one for another is a config change, not a rewrite.

Exploration and collection tools are built for a human — usually a developer, not an end reader — to manually construct requests, inspect responses, and share a curated set of calls with a team. Postman is the dominant tool here: it can import an OpenAPI spec to scaffold a collection, but its real value is the workflow around manual testing, environments, and scripted pre/post-request logic, not rendering. Insomnia plays a similar role with a lighter footprint.

Hosted developer portals go further than rendering: Readme.com and Stoplight combine spec rendering with versioning, changelogs, authentication for trying real calls, and onboarding content, aimed at external customers who need a polished, branded experience around your API rather than internal teammates reading a reference. Reaching for one of these only makes sense once you have external API consumers who need that onboarding experience — it’s overhead a purely internal API doesn’t need.

Picking a tool from the wrong category wastes effort: Postman doesn’t give you a polished public portal, and Redoc doesn’t give your own engineers a place to manually poke at endpoints during development. Start from what problem you’re solving — internal reference, manual exploration, or external developer onboarding — and the right category picks itself.

Check yourself

  1. 01What's the structural difference between a spec-first and a code-first workflow, and what does each one risk?

    Spec-first writes the OpenAPI document first and generates or validates code, docs, and mocks against it, risking slower upfront iteration since the contract has to be agreed before implementation starts; code-first writes the implementation first with inline annotations and generates the spec afterward, risking drift — a route that doesn't get annotated, or an annotation that doesn't match the handler's real behavior, ships an inaccurate spec that nothing catches automatically.

  2. 02Why does it make sense to think about documentation tooling as three categories instead of just picking "the best API doc tool"?

    Because a renderer (Swagger UI, Redoc), an exploration tool (Postman), and a hosted developer portal (Readme.com, Stoplight) solve different problems — rendering a spec for reading, letting a developer manually try requests and share collections, and giving external customers a branded, versioned portal with onboarding content — and a team often needs more than one of them at once rather than a single replacement for all three.

  3. 03What does putting a schema under `components.schemas` and referencing it with `$ref` buy you over inlining the same object definition in every operation that uses it?

    One definition that every operation referencing it stays consistent with — change the shape of a `User` object once in `components.schemas.User` and every path, response, and generated client that references it picks up the change, instead of hunting down and editing N duplicated inline copies that are free to silently diverge from each other.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark