Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



27 Commits

Repository files navigation


A proposal for transitioning between Swagger 2.0 and OpenAPI 3.0.x

Version 1.0.0-rc4

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

To aid the transition between Swagger 2.0 and OpenAPI 3.0.x, it is proposed to back-port the following features from the OpenAPI 3.0.0 specification (currently version 3.0.0) as specification extensions (formerly known as vendor extensions).

Tooling MAY make use of these features now, with minimal work required to support them in OpenAPI 3.0.x, definition authors MAY also use these features, knowing their API definition can be losslessly converted from swaggerplusplus to OpenAPI 3.0.x by any swaggerplusplus-compatible converter.


Path Version 3.0.x Object New Extension Type Description
#/ servers x-servers [Server Objects] When converting to OpenAPI 3.0.x, this array is used in place of any servers array converted from Swagger 2.0 metadata
#/paths/{Path Item} servers x-servers [Server Objects]
#/paths/{Path Item}/{operation} servers x-servers [Server Objects]
#/paths/{Path Item}/{Operation} trace x-trace V2 Operation Object This MUST be a Swagger 2.0 Operation Object, it MUST be treated as per any other Operation Object, for the TRACE HTTP method
#/paths/{Path Item} summary x-summary String Also as per Apiary extension
#/paths/{Path Item} description x-description String Also as per Apiary extension
#/parameters OR #/paths/{Path Item}/parameters OR #/paths/{Path Item}/{Operation}/parameters deprecated x-deprecated Boolean Indicates the parameter is deprecated and SHOULD be transitioned out of use
#/paths/{Path Item}/{Operation} callbacks x-callbacks [Callback Objects]
* within Schema Object anyOf x-anyOf [Schema Object] Schema MUST be extracted and post-processed before being used for validation
* within Schema Object oneOf x-oneOf [Schema Object] Schema MUST be extracted and post-processed before being used for validation
* within Schema Object not x-not Schema Object Schema MUST be extracted and post-processed before being used for validation
* within Schema Object required x-required Array Where a property has been removed from required due to use of x-anyOf, x-oneOf or x-not, converters MUST merge these arrays when converting from swaggerplusplus to OpenAPI 3.0.x. When a converter converts from 3.0.x to swaggerplusplus it MUST remove any required properties hidden by x-anyOf, x-oneOf or x-not and move them into this array.
* within Schema Object nullable x-nullable Boolean Indicates whether the property is nullable or not.
* within Schema Object discriminator x-discriminator Discriminator Object A version 3.0.x discriminator object to replace the version 2.0 discriminator property.
* within Response Object links x-links Map {Link Object} Links or references to reusable Link Objects
#/ components/links x-links Map {Link Object} Contains reusable Link Objects
#/ components/callbacks x-callbacks Map {Callback Object} Contains reusable Callback Objects


Converters MUST validate the specification extensions are of the expected type, and that mandatory properties (if any) are present. Failing that, they MUST leave the specification extension unchanged.

swaggerplusplus Tools

swaggerplusplus in the wild

Zappiti API