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.