apigenie window
Finds the support window of an OpenAPI document (the versions since its last breaking change) and writes the version annotations that let a client built from the newest version talk to a server of any version of the window. It then proves them by projecting the document back to each version.
(experimental, outside the 1.0 compatibility promise)
window, since 1.0.0, is the first version of version-aware clients: the annotations, the rules that end the window and the report can still change, and the client generators read only part of the annotations (see What the clients read). It says so in its--helpand on the first line it prints, on the standard error. See the experimental commands.
Usage
apigenie window [OPTIONS] SPEC
Description
A server of version 1.2.0 rejects a request with a property added in 1.3.0, and a client built from
1.3.0 doesn’t know that the property is new. window reads the history of SPEC, its release tags
by default, and walks back from the newest version. Every pair of consecutive versions is
compared as diff compares them. The window ends at the first pair
with a breaking change, or with a change that no annotation can describe to a client:
| End | The window starts at the newer version of the pair because |
|---|---|
breaking |
the change into it breaks clients |
blocking |
a request change an older server would reject and no annotation describes: a required request property removed, a constraint widened (with a configuration that rates it non-breaking), a changed type, a changed security scheme, … A change of title, description, deprecated, example, examples or externalDocs doesn’t count |
same-version |
the older revision has the same info.version, and they differ in what the annotations say: a server can’t tell them apart |
no-version |
the older revision has no info.version |
history-start |
the history has no older version |
Then window writes the annotations of every change of the window into SPEC, and
info.x-apigenie-versions, the versions of the window from oldest to newest, after info.version. The
document keeps its comments; YAML is written in block style. An operation of a path item that
SPEC takes from components.pathItems is annotated there. An annotation of SPEC whose version
its info.x-apigenie-versions listed, but the window no longer has, is older than the window: it is
taken out, and the report lists it under “Dropped”.
Before it writes anything, window checks its own work. It projects the annotated document to the
version of every revision of the window and compares the projection with that revision. The check
fails if a client of the projection would break, or if an annotated element differs: one is there
that shouldn’t be (an annotation missing, or too old), one is missing (an annotation too new), or
a parameter is required when it shouldn’t be. It also checks the annotated document as the
lint rule does: a version the generators
can’t place fails the run too. On a failure window names the version and the element, writes
nothing and exits with status 2.
The annotations
Each annotation names the version in which the change arrived. Two versions listed in
info.x-apigenie-versions are ordered by their position there; two semantic versions by SemVer
precedence (a v prefix and build metadata don’t count); otherwise a version that isn’t listed is
newer than a listed one. An annotation can use a listed version, or a semantic version when the
document has no list. On a parameter used through $ref, the annotations go next to the $ref and
apply to that use only. The
version-annotations-valid lint rule checks
annotations written by hand.
| Annotation | On | Means |
|---|---|---|
info.x-apigenie-versions |
info |
The versions of the window, oldest first |
info.x-apigenie-version-header |
info |
The response header that carries the server’s version (see apigenie-server) |
x-apigenie-added: VERSION |
operation, parameter, property, request body, request media type, security scheme | Absent before VERSION |
x-apigenie-removed: VERSION |
the same | Gone from VERSION; a version after info.version announces a removal |
x-apigenie-made-optional: VERSION |
parameter, property | Required before VERSION |
x-apigenie-made-required: VERSION |
parameter, property | Optional before VERSION |
x-apigenie-renamed-from: {version, name} |
parameter, property | Called name before version |
x-apigenie-type-changed-from: {version, schema} |
parameter, property | Had the schema schema before version |
x-apigenie-enum-added: {VALUE: VERSION} |
schema with enum |
VALUE is absent from the enum before VERSION |
A new alternative of a security requirement is annotated on its scheme under
components.securitySchemes, because a security requirement object can’t carry extensions.
Response changes need no annotation: a client ignores what it doesn’t read.
What the clients read
The TypeScript fetch and
Python client generators read part of what window
writes:
| Annotation | Read on | Ignored on |
|---|---|---|
x-apigenie-added |
operations, parameters, schema properties (optional in the types; only the top-level properties of a request body are gated) | request bodies, request media types, security schemes |
x-apigenie-made-optional |
request parameters, top-level request properties | nested request properties |
x-apigenie-made-required |
response properties | request parameters and properties |
x-apigenie-enum-added |
the schemas of parameters and top-level request properties | nested request properties |
x-apigenie-removed, x-apigenie-renamed-from, x-apigenie-type-changed-from |
everywhere |
A client of the newest version can still send what an ignored annotation gates to an older server.
History
By default the history is the release tags that match --tags and change SPEC, as for
changelog; --history commits takes every commit that changes
it. When SPEC in the working tree differs from its last revision, the working tree is the newest
version (SPEC (working tree)). A revision that can’t be read is skipped with a warning.
--history-spec replaces the git history with files.
SPEC must be self-contained: run bundle first if it refers to
other files.
Options
| Option | Description |
|---|---|
--history HISTORY |
Where the versions come from: tags (default), the release tags, or commits, every commit that changes SPEC. |
--tags PATTERN |
The glob pattern of the release tags, for example v*. Defaults to *. |
--from REV |
The oldest revision to consider, for example a tag. Defaults to the whole history. |
--history-spec FILE |
A version of the document, instead of the git history; repeat it, oldest first. SPEC is the newest version. Can’t be combined with --history, --tags or --from. |
--git GIT |
The git program. Defaults to git. |
--config FILE, --no-config |
The configuration file whose commands.diff block rates the changes, as for diff. |
--out FILE |
Where the annotated document goes, in the format of SPEC. Defaults to the standard output, and the report then goes to the standard error. --json needs it. |
--format FORMAT |
The report: text (default) or json. |
JSON output
With --format json the report is an object whose formatVersion member is the version of the
format, changed only when a member is removed or changes meaning (see
Compatibility). With the global
--json the report is the only thing on the standard output,
whatever --format says. --json therefore needs --out: without it window prints the status
and exits with 2. Its JSON Schema is
apigenie-window-report.json.
{
"formatVersion": 1,
"result": "annotated", // or "failed": a self-check failed, nothing was written
"document": "api.yaml",
"output": "annotated.yaml", // "" for the standard output, null when nothing was written
"window": {
"from": { "label": "v1.1.0", "id": "4f2c...", "version": "1.1.0" },
"to": { "label": "api.yaml (working tree)", "id": "api.yaml", "version": "1.3.0" },
"versions": ["1.1.0", "1.2.0", "1.3.0"],
"revisions": [{ "label": "v1.1.0", "id": "4f2c...", "version": "1.1.0" }, "..."]
},
"end": {
"reason": "breaking", // or blocking, same-version, no-version, history-start
"before": { "label": "v1.0.0", "id": "91ab...", "version": "1.0.0" },
"changes": [{ "location": "/paths/~1shipments~1{id}/get/responses/200/...", "change": "..." }]
},
"dropped": [], // annotations of SPEC older than the window, taken out
"annotationIssues": [], // what the lint rule reports on the result; "fails": true fails the run
"annotations": [
{ "annotation": "x-apigenie-added", "element": "#/paths/~1shipments~1{id}~1hold/post", "version": "1.2.0", "location": "..." },
{ "annotation": "x-apigenie-enum-added", "element": "#/components/schemas/ServiceLevel", "version": "1.3.0", "value": "same_day", "location": "..." }
],
"checks": [{ "revision": { "label": "v1.1.0", "id": "4f2c...", "version": "1.1.0" }, "status": "ok", "differences": [] }]
}
Exit status
| Status | Meaning |
|---|---|
| 0 | The window was found, every self-check passed, and the annotated document was written |
| 2 | Invalid options, a file that can’t be read or isn’t a self-contained OpenAPI 3.x document, no info.version, a git error, an invalid configuration, a failed self-check, or an annotation version the generators can’t place (nothing written) |
Examples
Annotate the document of the working tree from its v* release tags:
apigenie window api.yaml --tags 'v*' --out api.annotated.yaml
Annotate from released files and print a JSON report for a pipeline:
apigenie window api.yaml --history-spec api.1.1.yaml --history-spec api.1.2.yaml \
--out api.annotated.yaml --format json
Check annotations written by hand:
apigenie lint api.annotated.yaml