Over the past few years, an API description format called Swagger has quickly gained momentum. In order to reach it's full potential the specification was recently donated by its owner Smartbear, to the OpenAPI Initiative group. The OAI is a newly formed group under stewardship of the Linux Foundation and includes Microsoft, Google, IBM, Paypal, Atlassian, Captial One, Intuit, Smartbear and many others as its sponsoring members.

The Community Takes the Reins

In order to differentiate the specification, which is now being developed by a community effort, from the tooling owned by Smartbear, the Swagger specification was renamed to the OpenAPI specification. The term Swagger now refers only to the tooling owned by Smartbear to work with the OpenAPI specification. Work on the OpenAPI specification is being done on a Github repository by anyone who wants to get involved.

Every Hand Helps

I joined the OpenAPI Technical Developer Committee at the beginning of this year and have been involved in the regular meetings, responding to issues, creating new issues, reviewing PRs and creating PRs. As a developer on the Azure API Management team, I regularly work with OpenAPI specifications in my daily job. Understanding the challenges developers are facing with the current version of the specification and seeing where the next version is going, helps us make Azure API Management a better product for our customers.

It's In Microsoft's Blood

Microsoft have adopted version 2.0 of the OpenAPI specification as the primary API description format in many of its products. Azure API Management, Logic Apps, API Apps, Power Apps, Microsoft Flow, Visual Studio and AutoREST all have support for OpenAPI, although in most places the term Swagger is still used.

Progress Is Impossible Without Change

Over the last 8 months a core team, plus many community members, have worked on bringing a major update to the OpenAPI specification. OpenAPI V3.0 is now beginning to stabilize and the team are aiming to release the new version in January 2017.

Something For Everyone

The new version has simplified the overall structure of the document. It has added new ways to document an API and provide examples. There are more flexible options for hosting the API. Request and response payloads can now be described in both a simpler and more flexible way. URI parameters now support more of the capabilities defined by URI Templates and many of the limitations imposed on the use of JSON Schema have been lifted.

In addition to these improvements over how APIs were described with 2.0 of the specification, there have also been enhancements to support completely new scenarios. Webhooks can now be described with the new Callback objects. The notion of Linking has been added to enable statically describing the relationships between operations. This should provide the opportunity for documentation to provide significantly more contextual information and for client libraries to be much more user friendly.

More Work Ahead

There still remains a reasonable amount of work to complete the specification, and there is expected to be significant work done on tooling before all the issues can be considered closed. However, progress to date has been good and the target completion date looks achievable.

Stay In Touch, Get Involved

Follow the OAI blog for more details and watch out for more posts on planned changes. Don't hesitate to check out the Github repository to provide feedback on issues, pull requests for changes and to let the team know if you are working on 3.0 support for products and tooling.