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.0 | Becomes |
|---|---|
host, basePath, schemes | servers |
definitions, parameters, responses, securityDefinitions | components, with every $ref rewritten |
body and formData parameters | requestBody, one entry per consumes media type |
a response schema | content, one entry per produces media type |
| inline type keywords of other parameters and headers | their schema |
collectionFormat | style and explode |
collectionFormat: tsv | x-collection-format: tsv: 3.x has no tab style, but honig still encodes it |
type: file | type: string with format: binary |
x-nullable | nullable |
What is lost:
- An unknown
collectionFormatis read ascsv. - An unknown
OAuth2flowis read asimplicit. - A security scheme of an unknown
typeis 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.0 | Becomes |
|---|---|
nullable: true | "null" in type, in enum or in an anyOf branch |
boolean exclusiveMinimum and exclusiveMaximum | their numeric form |
example in a schema | examples: [example] |
x-jsonschema-* extensions | the JSON Schema keywords they carry |
x-oai-license-identifier | the license identifier |
What is lost:
allowEmptyValueandallowReservedon 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.1 | Becomes |
|---|---|
array-form items (JSON Schema 2019-09 and older) | prefixItems |
| an object where an array is required | an array of its values |
xml.attribute and xml.wrapped | xml.nodeType. With both, attribute wins |
x-tagGroups | tags[].parent, only when the mapping is unambiguous |
registered x-oai-* extensions | the 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:
allowReservedon a parameter that is not in the query. It was inactive in 3.1 and would change meaning in 3.2.