The Open API Initiative has announced the release of version 3.0.0 of the OpenAPI Specification (OAS).
The release marks the culmination of almost two years of development and a seven-month release process, beginning with an announcement in January 2017, followed by the release of an Implementer's Draft in February and a call for public comment in June. InfoQ has previously reported on the key new features of OAS 3.0, which include support for callbacks and multiple hosts and improved JSON Schema support, as well as new properties such as Components and Links.
Reaction from the community has been overwhelmingly positive, with congratulations and excitement pouring out on Twitter and increasing support for OAS 3.0 in open-source and commercial tooling. Version 3.0 is seen as a major milestone for the specification and for the Open API Initiative (OAI), which falls under the governance of the Linux Foundation.
Ron Ratovsky, member of the OAS Technical Developer Community (TDC), spoke with InfoQ about the path to 3.0 and the challenges the group faced bringing the specification to a new version. OAS has been managed through Github for almost three years, and the six-member TDC has reviewed and closed over 580 issues since September 2014, with over 200 still open. Discussing the large undertaking of organizing, discussing, and prioritizing requests, Ratovsky emphasizes the importance of considering the needs of a wide range of users while advancing the primary goal of OAS: to standardize and improve the description of REST APIs. To that end, support for new protocols and patterns such as GraphQL has been discussed but is not yet on the roadmap.
One new feature included in OAS 3.0 that seeks to address a widely discussed community need is the Links object, which some have called a "nod" to hypermedia. Stressing that the Links object is a static alternative to hypermedia, which is inherently dynamic and self-documenting, Ratovsky says, "We were thinking about how to do this and provide a solution, and we made it static as an initial step. We want more feedback on the Links feature before more development. We're looking to expand the feature and help even more when it comes to hypermedia."
The TDC is looking for feedback on more than just the Links object. Like most open source projects, OAS relies on community support and participation. "We honestly depend on community conversations and efforts – feature requests, comments, pull requests," says Ratovsky. "I hope to see more feedback from product managers and QA engineers and technical writers and anyone involved in the API lifecycle. How can the OAS make their jobs better?"
Users can find information on how to get involved and participate in the conversation on the OAS repository on Github. For those interested in learning more about implementing the new features and transitioning from Swagger 2.0 to OAS 3.0, SmartBear is hosting a webinar on August 9.