Awesome
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.
swaggerplusplus Tools
- Converter/validator
- Rebilly Redoc - supports a subset of swaggerplusplus