The latest version of the OpenAPI Specification, OpenAPI 3.0 (OAS 3.0), was released last year and is already gaining adoption from API developers and organizations looking to standardize on OAS.
OAS 3.0 was the first major release since the specification was donated to the OpenAPI Initiative, and renamed from the Swagger Specification to OpenAPI Specification in 2015.
At the end of last year, we had the opportunity to be joined by two members of the OpenAPI Initiative, Ron Ratovsky, member of the OAI Technical Steering Committee (and Swagger Developer Evangelist here at SmartBear), and Ole Lensmar, Chair of the OAI board, for a discussion on the newest features and enhancements in OAS 3.0.
In the 60-minute presentation, the speakers shared their insight on how the specification has been restructured, what new features they’re most excited about, and how API teams can start to transition to OAS 3.0.
The full video of our discussion is available here. But we also wanted to provide a more detailed breakdown, with clips and key takeaways from the presentation.
In this article, we will share some of the major updates in the latest version of OAS, and breakdown what you need to know when transitioning to OAS 3.0.
Simplified structure, with increased reusability
OAS 3.0 introduces a new, more simplified structure. The new structure is meant to make it easier to write and navigate OAS definitions — combining some of the existing objects from OAS 2.0, standardizing the naming used for different parts of the spec, and even introducing new objects to extend reusability within OAS 3.0.
The number of reusable components increased from 4 to 9, with the addition of new features like Links and Callbacks, which we cover in more detail later in this article.
Learn More:
Read the docs: OpenAPI 3.0 Structure
Content negotiation support
OAS 3.0 introduced a number of changes to how the body of a request and a response can be defined. One significant change is that body and formdata parameters have been removed and replaced with requestBody. The requestBody is more flexible in that it lets you consume different media types, such as JSON, XML, form data, plain text, and others, and use different schemas for different media types.
Other significant changes, include:
- Operations can now consume both formdata and other media types such as JSON.
- The consumes array is replaced with the requestBody.content map which maps the media types to their schemas.
- Schemas can vary by media type.
- Form data can now contain objects, and you can specify the serialization strategy for objects and arrays.
Learn more:
Read the docs: Describing Request Body
Enhanced Security Definitions
While the structure of the security definitions in OAS 3.0 remain consistent with OAS 2.0, there are some key changes that will impact how you describe security flows. One of the most noteworthy changes is that the OAuth 2 flows were renamed to match the OAuth 2 Specification: accessCode is now authorizationCode, and application is now clientCredentials.
Additional changes include:
- securityDefinitions were renamed to securitySchemes and moved inside components.
- type: basic was replaced with type: http and scheme: basic.
- The new type: http is an umbrella type for all HTTP security schemes, including Basic, Bearer and other, and the scheme keyword indicates the scheme type.
- API keys can now be sent in: cookie.
- Added support for OpenID Connect Discovery (type: openIdConnect).
- OAuth 2 security schemes can now define multiple flows.
Learn more:
Read the docs: Authentication and Authorization
Updated Parameter Types
As previously mentioned, OAS 3.0 removed two parameter types: body and formdata. OAS 3.0 also introduced a new parameter type, cookie, which was a requested update for documenting APIs that currently use cookies.
OpenAPI 3.0 also includes support for arrays and objects in operation parameters and lets you specify how these parameters should be serialized. The serialization method is defined by the style and explode keywords:
- style defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.
- explode (true/false) specifies whether arrays and objects should generate separate parameters for each array item or object property.
OpenAPI serialization rules are based on a subset of URI template patterns defined by RFC 6570.
Learn more:
Read the docs: Describing Parameters
Improved Examples
Examples are an important part of documenting your APIs. OAS 3.0 included an overhaul of how examples can be used within the specification, including the ability to describe multiple examples, reuse examples within your API definition, and reference external examples.
The changes to examples provide increased reusability when using example objects.
Learn more:
Read the docs: Adding Examples
Introducing OpenAPI Links
Links are one of the new features of OpenAPI 3.0. Links introduce an entirely new concept into the design phase of an API, used to show the relationship between responses and operations when designing the API.
Using links, you can describe how various values returned by one operation can be used as input for other operations. This way, links provide a known relationship and traversal mechanism between the operations. The concept of links is often compared to hypermedia, but OpenAPI links do not require the link information present in the actual responses.
Read the docs: OpenAPI Links
Support for Describing Callbacks
OAS 3.0 offers support for describing callbacks, which can be used to define asynchronous APIs or Webhooks. Callbacks let you handle requests that your service will send to some other service in response to certain events. This helps you improve the workflow your API offers to clients.
Callbacks use the same structure as other path definitions, and let you describe what the client is supposed to implement in order for the Webhook to work.
Read the docs: Callbacks
Additional Changes in OAS 3.0
In addition to some of the major changes to OpenAPI 3.0, there are some additional updates that will be important to know when transitioning to OAS 3.0.
- OAS 3.0 moves from GitHub Flavored Markdown (GFM) to CommonMark support.
- Extended JSON Schema support including
anyOf, oneOf, and not.
- Define multiple servers and template server definitions
- New support for TRACE method
Breaking changes from OAS 2.0 to OAS 3.0
If you’re ready to start converting to OAS 3.0, there are tools available to help restructure your existing definitions. SwaggerHub offers a built-in converter that will convert your existing specs into a 3.0-friendly format and make it easy to get started.
There are also a few important areas you’ll need to focus on when starting the process:
- Definitions, parameters, responses and securityDefinitions are all moved under components
- Schemes, hosts, and basePaths have been replaced by servers
- Parameters need to be restructured:
- Type definitions move under schema
- Body and formdata parameters extracted to a requestBody
- Responses need to be restructured:
- produces media types moved to this level
- Some security definition changes:
- 'basic' changed to 'http'
- OAuth2 flows renamed, given a slightly different structure
Additional resources for OAS 3.0
You can start designing and documenting APIs using OAS 3.0 in the open source Swagger Editor and Swagger UI, or within the SwaggerHub platform. We also compiled some of our favorite OAS 3.0 resources to help you get started: