Verified 2026-09 against https://spec.openapis.org/oas/latest.html (v3.2.1, 10 September 2026), https://docs.stoplight.io/docs/spectral and https://github.com/oasdiff/oasdiff.
1. The loop
- Change the document first. The OpenAPI file is reviewed in the pull request like code, before the handler exists. A contract argued about after the code is written is a contract nobody changes.
- Lint it with Spectral, using the base
spectral:oasruleset plus house rules (§3). - Diff it against the published version with
oasdiffand fail the build on a breaking change that has no version bump. - Generate what you can — clients, server stubs, mock servers, documentation — from the one file.
- Publish it as a build artefact, so "the spec" is never someone's local copy.
2. 3.1 or 3.2?
| OpenAPI 3.1 | OpenAPI 3.2.1 | |
|---|---|---|
| Released | 2021, universally supported | September 2026 |
| JSON Schema | Full JSON Schema 2020-12 | Same |
| Tooling | Every generator, linter and documentation tool | Catching up; check each tool you depend on |
| ASP.NET Core 10 | Emits 3.1 by default | Configurable |
Default to 3.1. Move to 3.2 when your linter, your generator and your documentation renderer all support it, and say so in the ADR — a document your pipeline cannot parse is worse than an older version of the same information.
3. A house Spectral ruleset
# .spectral.yaml
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-tags: error
all-operations-secured:
description: Every operation declares a security requirement (use [] for public ones).
severity: error
given: $.paths[*][get,put,post,delete,patch]
then:
field: security
function: truthy
errors-are-problem-json:
description: 4xx and 5xx responses use application/problem+json (RFC 9457).
severity: error
given: $.paths[*][*].responses[?(@property.match(/^[45]/))].content
then:
field: application/problem+json
function: truthy
collections-are-paginated:
description: A list operation must accept a limit parameter.
severity: warn
given: $.paths[?(@property.match(/^\/[a-z-]+$/))].get.parameters
then:
function: schema
functionOptions:
schema:
type: array
contains: { type: object, properties: { name: { const: limit } } }
npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=warn
Three rules cover most real review comments: every operation is secured, every error is problem+json, every collection is bounded. Add house rules only for things you have actually had to say twice — a ruleset with forty rules gets disabled wholesale the first time it blocks a release.
4. Breaking-change detection
oasdiff breaking https://api.example.com/openapi.yaml ./openapi.yaml --fail-on ERR
Run it against the published document, not against main, so a breaking change merged last week
is still caught today. What it catches that review misses: a response field becoming optional, an
enum losing a value, a parameter becoming required, a format change, a status code disappearing.
When a break is intentional, the same pull request carries the version bump and the deprecation headers. A suppression with no version bump is how a client finds out in production.
5. Generation, and what not to generate
| Generate | Why |
|---|---|
| Clients for internal consumers | Free, always in step with the contract |
| Mock server (Prism, or the spec's examples) | Consumers start before the provider exists |
| Documentation (Redocly, Scalar, Swagger UI) | One source, never a stale wiki page |
| Request validation middleware | The document becomes executable, so drift is impossible |
Server stubs are the doubtful one: generated handler skeletons rot the moment anyone edits them, and regenerating means a merge. Generating request validation from the document and writing the handlers by hand gives you the enforcement without the merge.
Where the code is the source of truth instead (attribute-driven generation in ASP.NET Core, schema- driven in Fastify), the workflow still works: generate the document in the build, commit or publish it, and run the same lint and diff steps. What matters is that a human reviews the document in the pull request — not which side produced it.
6. Owning the error catalogue
type URIs in problem+json are part of the contract: a client branches on them and they can never
change. Give them an owner and a home.
- One registry file listing every
type, its meaning, its status code and whether it is retryable. - The URI resolves to human-readable documentation. It need not, but a
typethat 404s trains everyone to ignore them. - Adding a
typeis additive and safe. Changing what one means is breaking, even though no schema changed — which is exactly why it needs a registry rather than a string literal in a handler. - Namespace them per service or module (
https://api.example.com/problems/orders/already-shipped) so two teams cannot collide.