production
OpenAPI & Documentation
Describe your API once in OpenAPI (formerly Swagger) — get docs, client SDKs, request validators, and contract tests for free.
OpenAPI (formerly Swagger) is a standard, machine-readable format for describing a REST API — its endpoints, parameters, request and response schemas, status codes, and authentication — in a single YAML or JSON document. The value is that one authoritative specification becomes the source of truth from which a whole ecosystem of tooling is generated, instead of hand-maintaining documentation, client libraries, and validators separately and watching them drift out of sync.
Architectural blueprint — the source of truth that everyone (builders, inspectors, electricians) works from.
Key Concepts
1
From one OpenAPI document you get a great deal for free. Interactive documentation (Swagger UI, Redoc) renders the spec into browsable, try-it-in-the-browser docs that stay accurate because they are generated from the contract. Code generators produce client SDKs in many languages and server stubs, so consumers do not hand-write HTTP plumbing. Request and response validators can enforce at runtime that traffic conforms to the schema, catching contract violations on both sides. Contract testing tools verify that a provider's implementation still matches what consumers expect, and mock servers can stand up a fake implementation from the spec so front-end and back-end teams work in parallel before the real API exists. The two common workflows are design-first, where you write the spec up front and generate code from it, and code-first, where annotations in the implementation generate the spec — each has trade-offs around who owns the contract.
2
The point worth making in an interview is that OpenAPI turns the API contract into a tangible, versionable artifact that drives documentation, tooling, and testing, which is what keeps a growing API consistent and consumable. The main risk to call out is the spec drifting from reality — documentation that lies is worse than none — so teams either generate the spec from the code or, in design-first shops, add CI checks that fail the build when the implementation diverges from the committed contract.
3
What the interviewer is probing.
What the interviewer is probing.
4
1. "What does OpenAPI give you beyond documentation?" *Probing:* the value. *Stalls:* "Docs."
*Moves up:* generated clients and servers, request validation, contract tests and mock servers from
one specification.
1. "What does OpenAPI give you beyond documentation?"
5
2. "Spec-first or code-first?" *Probing:* the judgement. *Stalls:* "Code-first." *Moves up:*
spec-first when several teams consume it, since the contract can be agreed before either side is
built; code-first is fine for internal APIs.
2. "Spec-first or code-first?"
6
3. "What makes documentation actually useful?" *Probing:* the user angle. *Stalls:*
"Completeness." *Moves up:* realistic examples, error cases, and auth setup — a field list without
an example is the most common complaint.
3. "What makes documentation actually useful?"
7
4. "How do you keep it from going stale?" *Probing:* the discipline. *Stalls:* "Review it."
*Moves up:* generate or validate it in the pipeline, so a drift between code and spec fails the
build.
4. "How do you keep it from going stale?"