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.
To learn more about what's new in OpenAPI 3.0, join us for a free training on September 26, OpenAPI 3.0: How to Design and Document APIs with the Latest OpenAPI Specification 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.
Learn more: Looking to Create OpenAPI 3.0 For Your API? Swagger Inspector Has Your Back
Where can I learn about OAS 3.0?
Here at Swagger we care a lot about the OpenAPI Specification so we're constantly creating resources for people to learn more about what's going on. Here are a list of our favorite OAS 3.0 resources:
We encourage you to also explore the OAI 3.0 documentation on GitHub to see what’s new in OAS 3.0.
Read the full announcement from the OpenAPI Initiative here.
Get started with OpenAPI 3.0
You can start designing and documenting new and existing APIs using OpenAPI 3.0 in SwaggerHub. The SwaggerHub editor lets you define and visualize your API using OpenAPI 3.0, or convert existing APIs defined with Swagger 2.0 to the latest version of the specification. You can also use Swagger Inspector to easily generate OAS 3.0 definitions from your exisiting APIs. Check out Migrating to OpenAPI 3.0: How to Convert Your Existing APIs with Swagger Tools to learn more!