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.
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.
Adopting an API First Approach with OpenAPI 3.0
This month, we are hosting a free training: Adopting an API First Approach with OpenAPI 3.0. In this training we will cover what it takes to adopt an API First approach to building products from the API’s design, how to position API design into your development workflow using the latest version of the OpenAPI Specification, OpenAPI 3.0, and effectively collaborate on an actual API design in a real world setting using the OAS and SwaggerHub.
Topics covered will include
- What is the API First approach to building applications?
- What does it take to adopt API First methodology?
- What is the OpenAPI Specification (OAS), and what are the newest features of OAS 3.0?
- How can OAS 3.0 accelerate API development, testing, documentation and delivery in the API First approach?
- Real world example of design an actual OAS interface for an API
The training is November 21 at 9am & 2pm ET.