version-annotations-valid
Since 1.0.0 · In the rulesets: Recommended at warning, Strict at warning, All at warning
This rule checks the version annotations that let a client built from the newest document talk to
servers of older versions: info.x-apigenie-versions and the x-apigenie- annotations on
operations, parameters, properties and schemas.
Rule details
The annotations are experimental, outside the 1.0 compatibility promise. apigenie window writes
them from the history of the document, and a client generator that understands them leaves out of
a request what the server’s version doesn’t know. A value it can’t read, or a version it can’t
place, makes the client guess, so the rule reports:
- a malformed value: a version that isn’t a string (quote
1.0in YAML), anx-apigenie-renamed-fromwithoutname, anx-apigenie-type-changed-fromwithoutschema, anx-apigenie-enum-addedthat doesn’t map enum values to versions; - an
info.x-apigenie-versionsthat isn’t a list of distinct version strings, oldest first, that doesn’t listinfo.version, or that lists versions after it; - a version the generators can’t place: with
info.x-apigenie-versions, one it doesn’t list; without it, one that isn’t a semantic version; - a version newer than
info.version, except inx-apigenie-removed, which can announce a removal with a version the list doesn’t have yet; - an
x-apigenie-removedat or beforeinfo.versionon an element the document still has; - an annotation on an element it doesn’t apply to, for example
x-apigenie-made-optionalon an operation orx-apigenie-enum-addedon a schema withoutenum.
Two listed versions are ordered by their position in info.x-apigenie-versions, two semantic
versions by SemVer precedence (a v prefix and build metadata don’t count), and a version that
isn’t listed is newer than a listed one: the order of apigenie window and of the generated
clients. The rule reports nothing in a document that uses none of the annotations.
Examples
Good.
openapi: 3.1.0
info:
title: Shipments
version: 1.3.0
x-apigenie-versions: [1.1.0, 1.2.0, 1.3.0]
paths:
/shipments/{id}/hold:
post:
x-apigenie-added: 1.2.0
responses:
"204":
description: Held
components:
schemas:
ServiceLevel:
type: string
enum: [standard, express, same_day]
x-apigenie-enum-added:
same_day: 1.3.0
Bad. A version the list doesn’t have, a version that isn’t one at all, and a rename without the old name.
openapi: 3.1.0
info:
title: Shipments
version: 1.3.0
x-apigenie-versions: [1.1.0, 1.2.0, 1.3.0]
paths:
/shipments/{id}/hold:
post:
x-apigenie-added: 1.4.0
responses:
"204":
description: Held
components:
schemas:
Shipment:
type: object
properties:
carrierRef:
type: string
x-apigenie-added: next
status:
type: string
x-apigenie-renamed-from:
version: 1.2.0
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
version-annotations-valid: off