swaggerplusplus

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.

Features

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

Conversion

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.