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.
- Path variables
- Query parameters
- 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
- Polymorphism (
/anyOf) allows you to to create an entity that can use the properties from different data types.
oneOfallows 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
oneOfcombination to get either all the properties of brain or all the properties of heart.
anyOfallows 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
anyOfcombination to create a data type containing any properties from either of these types.
anyOfcombination 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_weightproperty from the nervousSystem type and the
skull_heightand teeth properties from skeleton.
- 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.
- Bearer authentication
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.