Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Upgrading

honig generates from OpenAPI 3.2 only. A 2.0, 3.0 or 3.1 description is upgraded one version at a time: 2.0 to 3.0, 3.0 to 3.1, then 3.1 to 3.2. Run cargo honig upgrade to see the result.

Most of a description carries over unchanged. Each change below prints a warning that points at the field. cargo honig generate prints them unless you pass --quiet.

Swagger 2.0

Swagger 2.0 to OpenAPI 3.0.

2.0Becomes
host, basePath, schemesservers
definitions, parameters, responses, securityDefinitionscomponents, with every $ref rewritten
body and formData parametersrequestBody, one entry per consumes media type
a response schemacontent, one entry per produces media type
inline type keywords of other parameters and headerstheir schema
collectionFormatstyle and explode
collectionFormat: tsvx-collection-format: tsv: 3.x has no tab style, but honig still encodes it
type: filetype: string with format: binary
x-nullablenullable

What is lost:

  • An unknown collectionFormat is read as csv.
  • An unknown OAuth2 flow is read as implicit.
  • A security scheme of an unknown type is kept as written. Generated code does not use it.

OpenAPI 3.0

OpenAPI 3.0 to 3.1. Schemas move from the 3.0 dialect to JSON Schema 2020-12.

3.0Becomes
nullable: true"null" in type, in enum or in an anyOf branch
boolean exclusiveMinimum and exclusiveMaximumtheir numeric form
example in a schemaexamples: [example]
x-jsonschema-* extensionsthe JSON Schema keywords they carry
x-oai-license-identifierthe license identifier

What is lost:

  • allowEmptyValue and allowReserved on a header. 3.0 allowed them there without effect. 3.1 has neither.
  • A registered extension whose field is also set. The field wins.

OpenAPI 3.1

OpenAPI 3.1 to 3.2.

3.1Becomes
array-form items (JSON Schema 2019-09 and older)prefixItems
an object where an array is requiredan array of its values
xml.attribute and xml.wrappedxml.nodeType. With both, attribute wins
x-tagGroupstags[].parent, only when the mapping is unambiguous
registered x-oai-* extensionsthe 3.2 fields they carry: $self, additionalOperations, itemSchema, itemEncoding, prefixEncoding, encoding, dataValue, serializedValue, the name of a server, the summary of a response and the deprecated and device authorization flow of a security scheme

What is lost:

  • allowReserved on a parameter that is not in the query. It was inactive in 3.1 and would change meaning in 3.2.