We're excited to announce that one of our most requested features is now complete! The new API Explorer accepts the OpenAPI 3.0 Specification.
Background
The OpenAPI 3.0 (OAS 3.0) Specification used to be known as the Swagger 2.0 Specification. And while we still support Swagger 2.0 files, the new API Explorer gives you the option to upload either specification when you add an API.
How we did it
When OAS 3.0 was released about a year ago, we blogged about the changes in "A Visual Guide to What's New in Swagger 3.0". At the time, ReadMe only accepted Swagger 2.0 files. Since the new API Explorer natively supports OAS 3.0, we have been using the excellent swagger2openapi package behind the scenes to convert specifications from Swagger 2.0 to OAS 3.0.
Then in May, the swagger-parser package we use to parse, validate and resolve Swagger/OAS files released support for OAS 3.0! This vastly simplified the work required for us to integrate this into ReadMe.
How you can get it
OAS 3.0 files are only supported in the new API Explorer, which has been automatically turned on for ReadMe projects created after July 6th 2018.
For older projects, we will soon enable you to switch on the new API Explorer in your ReadMe project settings.
If you want it now, email [support@readme.io](mailto:support@readme.io?subject=New API Explorer) and we'll turn on the new API Explorer for you! Please test the new API Explorer on your current Reference documentation using the ?newApiExplorer=true query parameter first and let us know if you spot any issues.
We've also created new API endpoints to handle OAS 3 files. Our CLI program rdme does not have a dedicated oas command, but providing your OAS file to the rdme swagger command will work.
Shoutouts
Special thanks to @BigStickCarpet for your continued development on swagger-parser and @yujunlong2000 who submitted the pull request to add support!