OpenAPI Specification 3.0 support
OpenAPI Specification 3.0 comes with new features, bringing more expressivity and productivity to API designers.
For more information about OpenAPI, see the Swagger documentation.
Components
- Path variables
- Query parameters
- Headers
- Responses
Combinations
- Composition (allOf) allows you to aggregate schema properties from different schemas. For example, you can define a data type anatomy by reusing all the properties from the existing types nervousSystem, skeleton and digestiveSystem.
- Polymorphism (oneOf
/anyOf) allows you to to create an entity that can use the
properties from different data types.
- oneOf allows you to define a data type containing the properties of one of the selected types. For example, if you create an operation to get information about an organ, you can define the response using the oneOf combination to get either all the properties of brain or all the properties of heart.
-
anyOf allows you to define a data type containing the
properties of one or several of the selected types. For example, you can
define a data type nervousSystem and a type
skeleton containing different properties, and use
the anyOf combination to create a data type containing any
properties from either of these types.
An anyOf combination is valid as long as it contains all the required parameters of at least one of the data types selected. The example below uses the brain_weight property from the nervousSystem type and the skull_height and teeth properties from skeleton.
For more information about composition and polymorphism, see Inheritance and Polymorphism and Difference Between anyOf and oneOf.
Responses
- Response ranges: instead of defining a response such as 200, you can set it as 2XX, so that it includes responses from 200 to 299.
- Default responses: you can define a default response to be returned when a specific or range response is not defined.
- The 204 response is defined and takes precedence over the others.
- The 2XX response applies to response codes 200 to 203 and 205 to 299.
- The default response applies to all 1XX, 3XX, 4XX, and 5XX responses.
Security
- Bearer authentication
- OpenIdConnect
Restrictions
OAS 3.0 allows you to indicate that some properties are read-only or write-only.
This option is available in data types only and cannot be defined in requests or responses at the operation level.