We are excited to announce that the next generation of the OpenAPI Specification (OAS) is officially released!
OAS 3.0, which is based on the original Swagger 2.0 specification, is meant to provide a standard format to unify how an industry defines and describes RESTful APIs. The release of OAS 3.0 marks a significant milestone in the growth of the API economy — bringing together collaborators from across industries, to evolve the specification to meet the needs of API developers and consumers across the world in an open and transparent manner.
SmartBear Software donated the Swagger 2.0 Specification to the OpenAPI Initiative when the Swagger team joined SmartBear in 2015. We are excited to see how API providers that rely on the specification to design, document, and develop APIs, will be able to further their API development with OAS 3.0.
What’s new in OAS 3.0?
The development of OAS 3.0 was truly a collaborative effort — not just for the members of the OpenAPI Technical Development Committee and the 27 members of the OAI, but also for the thousands of developers and architects that contributed to the efforts, sent in pull requests, and provided feedback, which helped drive the evolution of the spec.
We will be releasing a number of new resources and trainings around OAS 3.0 in the coming weeks, but for now here’s an overview of some of the new updates and capabilities you can expect in 3.0:
- The overall structure of the specification was refactored for better reusability
- Added Support for describing callbacks
- Links to express relationships between operations
- The JSON schema includes support for: oneOf, anyOf and not
- Improved parameter descriptions, including the ability to use a schema
- Better support for multipart document handling
- Cookie parameters are in; dataForm parameters are out
- Body parameters have their own entity
- Better support for content-type negotiation
- The security definitions have been simplified and enhanced
What does this mean for Swagger?
There have been a lot of questions around what the release of a new spec, with a new name, means for the future of Swagger. As a team that has been developing tooling around the specification for 6+ years, the Swagger project will continue to be a class of high quality tooling to better implement the OAS.
Some of the tools Swagger has produced are the Swagger UI and the Swagger Editor. The Swagger UI gave life to the OpenAPI Specification (formerly the Swagger Specification), allowing users to visualize and interact with the API in a format that’s easy to read and understand. The Swagger Editor, another popular open source project, is the de facto open source editor for designing APIs in the OpenAPI Specification. These are just some of the many tools Swagger continues to develop and grow to allow developers and consumers to take advantage of the OAS.
We will continue to invest in evolving these tools, and other Swagger projects to fully tap into the power of OAS 3.0. In the coming weeks, we’ll be sharing more details on when 3.0 support will be coming to the different Swagger tools, as well as what 3.0 means for the SwaggerHub platform. In addition, you can expect to see some exciting new Swagger projects being released by the team in the weeks, months, and years to come!
What does OAS 3.0 mean for APIs using Swagger 2.0?
In the short term — nothing. You can continue to use Swagger 2.0 with any of the Swagger tooling, SwaggerHub, or any other platform that supports the 2.0 spec. We will continue to support the use of 2.0 specs for the foreseeable future.
We are working on tools to help in the process on transitioning to 3.0 now, so keep an eye out for what’s coming next.
Where can I learn about OAS 3.0?
As mentioned, we will be rolling out new resources, training, and documentation on 3.0 in the coming weeks.
We encourage you to explore the OAI 3.0 documentation on GitHub to see what’s new in OAS 3.0.
Join us on August 9 for a free OAS training.
On August 9, SmartBear and the Swagger team will be presenting a live online training on OAS 3.0 — OpenAPI 3.0, And What it Means for the Future of Swagger.
The training will be presented by Ole Lensmar, CTO, SmartBear Software & Chair of the OpenAPI Initiative and Ron Ratovsky, Swagger Developer Evangelist and Member of the OpenAPI Technical Development Community.
During this training, we will introduce some of the newest features coming in OAI 3.0. We will also share insight into the work being done in the Swagger community, and showcase some of the excited developments for the Swagger tooling.
Get a head start on OAS 3.0! Reserve your spot.
(Can’t make the training? RSVP and we’ll make sure to send you a recording of the training.)