Some background about Swagger & OpenAPI spec
Swagger is a kind of open REST API definition spec.
The Swagger specification development started in 2010. In 2015, Swagger is donated and renamed as OpenAPI Initiative under the Linux Foundation, in order to advance a common standard across industries. A number of tech companies, including Google, IBM, and Microsoft, signed on as founding members of the OpenAPI Initiative, and the Swagger Specification was rebranded as the Open API Specification.
Nowadays, OpenAPI-Spec 2.0 has become the most popular REST API definition spec. (Even more popular than RAML & API Blueprint)
OpenAPI-Spec 3.0 Release Candidate is out in Feb
In Feb 2017, OpenAPI-Spec 3.0 is currently out as release candidate and considered feature completed.
For the spec details, you may have a look at their Github:
I also found two blog articles which mentioned some highlight changes in 3.0:
Highlight Features Previews
I previewed some highlight changes about the Swagger 3.0. It has some pretty good support features which would definitely help on REST-API’s daily-life usages.
1) Introducing “examples” definitions, which allow defining examples for operation request/responses. (Lacking in 2.0)
2) Support defining multiple servers (instead of single host definition in 2.0)
3) Introducing “linking“, which for describing hypermedia (e.g: HATEOAS)
I think the “examples” object is a specially-great feature because:
1) Making API Friendly to Test-driven practices
People can leverage OpenAPI3 examples definitions to describe API example requests/responses.
Hence tools would be able to easily make API mockups/stubs for testings.
Hence, it may be more friendly to Test driven practices.
2) Better in API documentation with examples
In OpenAPI2, with Swagger-UI library, we can already use the API spec to generate a developer friendly Document UI page for REST APIs.
The OpenAPI3’s “examples” definition can be a complement part in the Swagger-UI to show example requests/responses, which is lacking in existing 2.0 version.
P.S. Below is the revision history of Swagger/Open API
Version Date Notes
||Implementer’s Draft of the 3.0 specification
||Donation of Swagger 2.0 to the Open API Initiative
||Release of Swagger 2.0
||Initial release of the formal document.
||Release of Swagger 1.1
||First release of the Swagger Specification