49. OpenAPI/Swagger specifications and API documentation
Answer as submitted
“Yes — OpenAPI/Swagger is my standard way of defining, documenting and validating API contracts.”
Expanded answer
Yes, and I use it as the contract rather than as the documentation that follows the contract. Authoring: design-first where a consumer outside the team depends on the API, because the largest value of a specification is agreeing the shape before anything is built; code-first from the implementation where the consumers are internal and the API is still moving, with Swashbuckle or NSwag in .NET, springdoc-openapi in Java and the native schema in FastAPI. What is never acceptable is both at once — a hand-written document beside a generated one — because that is how a specification becomes a guess. Tools: Swagger UI so QA and partners explore and call the API without a hand-written collection, a mock server generated from the document so front-end work starts before the endpoint exists, typed clients generated for the SPA and for partner integrations so no DTO is maintained by hand, and schema validation in the pipeline so the document cannot quietly become invalid. Governance: the versioning and deprecation policy expressed in the document itself rather than only in a wiki, one naming and pagination convention so a consumer learns it once, security schemes and rate limits documented with the actual numbers, and a catalogue generated from the documents so nobody has to ask which service and version to call. Style is written for the person integrating rather than for the person who wrote the code: every parameter and field says what it means and what happens when it is wrong, examples are realistic rather than string, the business rules a consumer would otherwise ask about are written where they will look, and every error status is enumerated with its payload so error handling is designed instead of discovered. Enforcement is what makes all of it true: a house ruleset linted on every pull request, validation against the OpenAPI dialect, a diff against the published version so a breaking change cannot ship inside an existing major version, contract tests that fail when the implementation drifts, and publication from the pipeline so the portal can never show a version that does not exist.
| Stage | Decision | What it prevents |
|---|---|---|
| Authoring | design-first with external consumers, code-first internally, one source of truth | a hand-written document drifting beside a generated one |
| Tooling | Swagger UI, mocks from the spec, generated typed clients, schema validation | hand-maintained DTOs and front-end work blocked on an unfinished endpoint |
| Governance | versioning and deprecation in the document, one convention, an API catalogue | every service inventing its own pagination and its own deprecation notice |
| Style | descriptions that answer questions, realistic examples, all error statuses enumerated | support tickets for things the document could have said |
| Enforcement | lint, dialect validation, breaking-change diff, contract tests, publish from CI | a contract that describes a previous version of the API |
| Deprecation | a date, a replacement and a Sunset header on every deprecated operation | a deprecated: true nobody can plan around |
Live specification-lifecycle workflow proof
The running component below changes its stage/result view through real event binding. Select a stage to see the decision, the reasoning behind it, and the evidence that holds it up.
Choose a stage of the specification lifecycle
Select a stage to inspect the decision, the reasoning and the evidence.
$ design-first where an external consumer depends on it · code-first (Swashbuckle/NSwag, springdoc-openapi, FastAPI) for internal contracts · one source of truth per API
The contract is authored design-first when a consumer outside the team depends on it, because the largest value of a specification is agreeing the shape before anything is built. It is generated code-first from the implementation where the consumers are internal and the API is still moving: Swashbuckle or NSwag in .NET, springdoc-openapi in Java, the native schema in FastAPI. What is never acceptable is both at once — a hand-written document beside a generated one — which is how a specification becomes a guess.
APIs with a hand-written spec beside a generated one: 0 design-first where an external consumer depends on the contract: yes code-first where the implementation is the source of truth: yes OpenAPI version in use: 3.1, with 3.0 only where a tool lags
What the specification buys
deprecated: true alone cannot be planned around; generate the catalogue from the documents so it can never list a version that does not exist; and diff against the published version on every change, so a breaking change needs a new major version rather than an apology.
Source files
Select a file to inspect the proof with syntax highlighting and line numbers. The first file is the code running the component above; the others are the specification itself, the house ruleset that enforces it, and the tests that detect drift and reject a breaking change.
Acceptance criteria
- Treats the specification as the contract, not as documentation written afterwards.
- States when design-first and code-first apply, and refuses having both.
- Shows an interactive proof of choosing a stage and reading the evidence.
- Documents every failure a consumer must handle and shows a realistic example on every schema.
- Enforces the contract in CI, including a breaking-change gate against the published version.