What´s New in Open API Specification (OAS 3.0)
Open API Specification (formerly called the Swagger Specification) is a contract description format of APIs for the REST architectural standard. An OpenAPI file allows you to describe your API, including:
- Route availability (GET / users).
- Parameters of input and output of each route (query parameters, header parameters or body).
- Authentication methods.
- Contact information, license, terms of use and other information.
- Support for API-first and Code-first approaches for defining, building and documenting APIs.
Specifications can be written in YAML or JSON message format.
What happened to Swagger?
To understand what happened to Swagger, we will first address the institution that is taking care of this new version of the specification, being it the Open API Initiative (OAI).
A consortium of technology industry experts, with the goal of standardizing how REST APIS are described, created the Open API Initiative (OAI).
As an open governance structure under the Linux Foundation, OAI is focused on creating, evolving and promoting a neutral description format for any vendor. SmartBear Software donates the Swagger Specification directly to the OAI as the basis of the Open API Specification.
Therefore, the Open API Specification is the evolution of Swagger Specification and is titled OAS 3.0, being the official release date 7/26/2017.
So, What is new in OAS 3.0?
With this new version of the specification the main features are:
- Improved reusability.
- Improves contract writing. Swagger was verbal.
- New type: cookie.
- All parameters support complex types.
- Content Negotiation Support.
- Requests and responses support various types of negotiation for different content types (application/json or text/xml).
- Support for callbacks description.
- Possibility of defining asynchronous APIs.
- Links to express relationships between operations.
- Examples on the routes.
- Improved security settings.
- OpenID Connect support.
Roadmap OAS 3.0
The new version has just been released, but tools that continue under the Swagger Tools name are undergoing releasing.
All of these tools are open source projects, governed by OAI and Smart Bear.
Therefore, several vendors support the Swagger Specification 2.0 in their products. However, vendors will make these new functionalities available in their products according to the evolution roadmap of each product.
Conclusion
The new specification is not retro compatible, meaning the existing API specifications will have to go through a migration.
This point is not a big problem, as the way of writing the contract has evolved, but the API contract itself remains the same, i.e. the backend implementation is maintained and the API exposure tools and products through the contract will have to migrate these settings at some point.
For Swagger 2.0 users, these modifications bring a major breakthrough in writing REST API contracts, as this new specification makes rewriting contracts easier and brings examples to facilitate the generation of automated sandboxes.
These new features come from ongoing API contract usage learning with a focus on automating the API life cycle.
