Announcing OpenAPI Specification 3.0 Support for Building Great APIs

  October 21, 2017

It’s quite fascinating to see the evolution of a small, renegade open source project change the perception of an entire industry. This is what happened with the Swagger Specification, the open source API design standard that went on to develop an entire community of developers, a powerful ecosystem of tools around it, and eventually evolve to become the OpenAPI Specification (OAS), the world’s standard for defining RESTful services. Being the company and team behind the initial versions of the Swagger Specification, it’s been a privilege to be a part of this innovation. Today, we are pleased to announce support for the next version of the OpenAPI Specification, 3.0 in SwaggerHub.

Why OpenAPI Specification 3.0

OAS 3.0 brings a variety of rich, expressive capabilities into the forefront of your API design. The structure has been refactored to be much more simple. For example, reusable objects like parameters, responses, examples and more, are swept under the components object, and the confusing body parameter has been replaced with requestBody, which also groups formData under it. There’s also an array of new capabilities like linking, callbacks, multiple server hosts, and better security definitions. You can learn more about all the new changes in our upcoming training: OpenAPI 3.0: How to Design and Document APIs with the Latest OpenAPI Specification. The feature rich description set of OAS 3.0 allows architects, developers, and technical writers better describe their APIs without restrictions, and makes for an enhanced consumption experience. The industry is moving forward with the adoption of OAS 3.0, and there’s new tooling built around the specification. Last month, we provided support for OAS 3.0 in the Swagger Editor and UI, and Swagger Core, and this has now been extended to SwaggerHub so your teams can collaborate on their API design and documentation process using the OAS 3.0.

What can SwaggerHub offer?

Design and Documentation

The SwaggerHub editor supports OAS 3.0 to design and document REST APIs. This means you can take advantage of the editor’s auto-complete, error feedback, and syntax validation when designing APIs, while simultaneously visualizing your OAS APIs. SwaggerHub auto-generates and hosts the documentation of your OAS-defined APIs as well, so you have one platform for all your API design and documentation needs. When creating new APIs, you can specify which version of the specification you want to use, giving the flexibility to define APIs in the specification that best suites your needs. SwaggerHub can also automatically determine the type of the specification if you choose to import your definition. It’s easy to identify if your API is defined in the latest OAS on SwaggerHub with the OAS3.0 badge.

Swagger to OAS 3.0 Conversion

One of the biggest challenges whenever a new version of a framework is introduced is migration. SwaggerHub has your back with the ability to convert existing Swagger 2.0 specifications to the latest OAS 3.0. This instant conversion will create a new version of your API in the -oas3 suffix. Your original API version will remain unchanged. This means you no longer have to sit for hours trying to decipher and change every single line in your API definition, or plumb your way through your API with plugins to upgrade to the latest version, just hit convert and see your definition converted to OAS 3.0.

Great! Why is OAS 3.0 support still in beta?

While we have great support for designing, documenting, converting, and collaborating on APIs using the OAS 3.0, there are still a few additional capabilities we’re working on to provide full support for OAS 3.0. This includes –
  1. Making the documentation of OAS3.0 based APIs interactive
  2. Enabling mocking capabilities for OAS 3.0 based APIs
  3. Generating server code and client SDKs from the OAS 3.0 API
  4. Adding OAS3.0 support for SwaggerHub Domains
That said, we’re actively working on adding the above capabilities as soon as possible. Any feedback or feature requests from our users is always appreciated, so feel free to email us directly at [email protected] with input on our OAS 3.0 support.  You can learn more about using OAS 3.0 from our help documentation.  

Get started with OpenAPI 3.0

You can start designing and documenting new and existing APIs using OpenAPI 3.0 in SwaggerHub. The SwaggerHub editor lets you define and visualize your API using OpenAPI 3.0, or convert existing APIs defined with Swagger 2.0 to the latest version of the specification. Get started today.