Runscope API Monitoring and Testing    Learn More →

Tutorial - Converting your Swagger 2.0 API Definition to OpenAPI 3.0

By Heitor Tashiro Sergent on .

 
Open API Initiative logo with the text "2.0 -> 3.0" underneath it
 

At the end of July, the OpenAPI Specification 3.0.0 was finally released by the Open API Initiative. It's a major release, and after 3 years in the making, it brings about a lot of improvements over the 2.0 specification, making it possible to create definitions for a broader range of APIs.

What's New in OpenAPI 3.0.0

There're a lot of new features that were added to this version, such as:

  • Added support for multiple root URLs.
  • Added support for content type negotiation.
  • Extended JSON Schema support to include `oneOf`, `anyOf` and `not` support.
  • Added a callback mechanism to describe Webhooks.

Those are just a few of the changes in the new specification. For more information on what's new, I highly recommend checking out:

Converting Your API Definition

We can convert our v2.0 API definition with the swagger2openapi open-source project made by Mermade Software. You can find a hosted version of the web app here:

After opening the URL above, just paste or upload your API's v2.0 definition, make sure that the Validate checkbox is unchecked, and click on Convert Swagger/OpenAPI 2.0:

Then openapi-converter.herokuapp.com website, with the Convert tab selected, and the first few lines in JSON of the Runscope v2.0 API schema in the "Paste Swagger 2.0 here:" textbox, and the "Validate" checkbox unchecked.

If you have a valid definition, the app should return the converted v3.0.0 version for it:

The result page after hitting "Convert Swagger/OpenAPI 2.0" button in the converter app, showing the first few JSON lines of the Runscope API schema, now in v3.

You can check out our Runscope API v2 definition, and the resulting converted v3 file on GitHub.

Should I update my specification?

That depends. It'll be a while until all the tools that supported v2.0 also support the new v3.0.0, so it's really going to vary on how you're using the specification. But, if you couldn't describe your API before because of features that are now available, now is a good time to start building your API definition. 😄

You can find a list of tools that support v3.0.0 in the OAI-spec GitHub repository, and you can also check out our Swagger/OpenAPI resource guide.


Do you have an OpenAPI 2.0 definition for an API you'd like to start monitoring? Learn more about how you can import it into Runscope and sign up for your free trial account today.


Categories: apis, tutorial, swagger, openapi

Everything is going to be 200 OK®