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:
- A Visual Guide to What's New in Swagger 3.0 by ReadMe.io - This is a great blog post by the folks at ReadMe.io, and it includes code examples showing what objects look like in v2.0 vs. v3.0.0.
- Open API Initiative - Explaining the 3.0 Spec, Series of Posts by Darrel Miller - This series by the OAI itself is a great breakdown on some of the changes made in the new spec, and can give you some insight into the discussion around them.
- Comparing OpenAPI/Swagger 2.0 and 3.0.0-rc1 by Mike Ralphson - Here you can find a step-by-step comparison of what an API definition for v2.0 and its converted v3.0 objects look like.
- OpenAPI Specification v3.0.0 on GitHub - The repository for the specification is really well written and includes all the objects and definitions supported in the new schema. This is a great resource if you're already familiar with v2.0 and want to use this as reference material.
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:
If you have a valid definition, the app should return the converted v3.0.0 version for it:
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.