58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
# OpenAPI 3.2: the experimental lane
|
|
|
|
## Why it is a lane rather than an upgrade
|
|
|
|
Generating 3.2 is cheap. Adopting it is not, and the two get conflated because the generated
|
|
document looks fine.
|
|
|
|
The value of an API description is entirely in what consumes it. A document in a version a client
|
|
generator does not fully understand does not fail — it produces a client that compiles and is wrong,
|
|
which is worse than no document at all.
|
|
|
|
So 3.1.2 stays the release artifact and 3.2 is generated beside it, with a report.
|
|
|
|
## The invariant
|
|
|
|
**Generating 3.2 must not change the 3.1 snapshot.** Both come from the same model, so a contributor
|
|
that mutates it on the way to 3.2 changes the artifact that is actually shipped — silently, and only
|
|
when the experimental lane runs.
|
|
|
|
`OpenApi32CompatibilityReport` hashes the snapshot before and after, and a difference is a promotion
|
|
blocker with its own message.
|
|
|
|
## The toolchain matrix
|
|
|
|
Four kinds of tool, checked separately, because passing one says nothing about the others:
|
|
|
|
| Kind | What it catches | What it misses |
|
|
| --- | --- | --- |
|
|
| Parser | Structural errors | Anything semantically odd |
|
|
| Linter | Style rule violations | Accepts documents a parser rejects |
|
|
| Generator | Unsupported constructs — sometimes | Usually emits a wrong-but-valid signature instead of failing |
|
|
| Client compile | The wrong signature the generator emitted | Runtime behaviour |
|
|
|
|
`OpenApiToolchainMatrix.complete()` requires at least one passing tool of each kind.
|
|
`gaps()` names the kinds that have none.
|
|
|
|
"OpenAPI 3.2 works" is not a statement anybody can make. "This document is read correctly by these
|
|
four tools at these versions" is.
|
|
|
|
## Streaming descriptions
|
|
|
|
The substantive difference between 3.1 and 3.2 for this application is how streaming responses are
|
|
described. Those differences are reported separately rather than folded into a pass/fail, because a
|
|
green pass hides what changed.
|
|
|
|
## Promotion
|
|
|
|
`promotionBlockers(adrAccepted)` always includes the ADR blocker until one is accepted, however
|
|
green the matrix is. A machine-checkable matrix cannot decide whether the consumer population is
|
|
ready; that is a judgement, and it belongs in
|
|
`docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`.
|
|
|
|
## Running it
|
|
|
|
The experimental generation runs in its own workflow and publishes the 3.2 document and the
|
|
compatibility report as artifacts. It never runs in the release workflow, so the release artifact
|
|
cannot depend on whether it ran.
|