Everyone is talking about OpenAPI 3.0. Your boss probably heard it being referenced by some analyst, your friends at that cool startup down the road use it to better define their microservice based application, and your product manager cousin couldn’t stop talking about how easy it makes consuming APIs last Thanksgiving.
You’re intrigued, and after some research, you've realized just how beneficial it is to define your APIs with OAS 3.0. But what if everyone who’s raving about the OpenAPI designed their API first with the specification before they implemented their API? Your company has dozens of legacy APIs that were implemented and deployed long before the OpenAPI ever caught on.
So how do you create the OpenAPI documentation from an existing API?
You could spend hours researching the best plugins to help you generate this specification, make sure the plugin supports the language of implementation, and then spend more time annotating each of your API endpoints with this plugin to finally create this specification. Or you could use Swagger Inspector’s latest support for generating OpenAPI 3.0 documentation with just a few clicks.
OpenAPI 3.0 Simplified
OpenAPI has changed the REST API landscape forever. It’s provided a common framework for humans and machines to understand, work with, and consume the API. It acts as the standard template for developers to easily build the API, detailing the different resources and their associated request-response cycles. OpenAPI 3.0 brings a wealth of additional capabilities on top of the previous Swagger 2.0 specification, some of which include –
- The overall structure of the specification was refactored for better reusability
- Added Support for describing callbacks
- Links to express relationships between operations
- The JSON schema includes support for: oneOf, anyOf and not
- Improved parameter descriptions, including the ability to use a schema
- Better support for multipart document handling
- Cookie parameters are in; dataForm parameters are out
- Body parameters have their own entity
- Better support for content-type negotiation
- The security definitions have been simplified and enhanced
OpenAPI 3.0 definitions can help automate different API lifecycle processes, including creating interactive, consumer friendly documentation, prototyping client SDKs and generating test cases.
Everyone’s always looking to get the best out of the OpenAPI 3.0, and clearly there’s some great features for your APIs. But what does Swagger Inspector’s new OAS 3.0 support have to do with any of this?
Instantly Generate OpenAPI 3.0 From Existing APIs
The design first approach advocates for designing the API first with the OpenAPI Specification before the actual code, implementation, testing and documentation is done. But while the design first approach is ideally what every developer should strive for, it’s not always easy to accomplish.
Many times, organizations have tons of existing APIs that have already been implemented and deployed, without any definition in place. There are also many practical reasons as to why a company or team might not design their API first in their API programs moving forward.
This is where Inspector comes in. With Swagger Inspector, you can kiss the dilemma of time consuming, code-first, OpenAPI generation goodbye! Inspector allows you to generate an OpenAPI definition from an existing API endpoint in a matter of minutes with a few clicks. To do this, insert the base URI and path of the API you’d like to define in OpenAPI into the form field. You can always add any authentication, headers, or query parameters if needed, and then press SEND.
Once you get a valid response, you can generate the OpenAPI file from the right panel, under the History tab. The cool thing about Inspector is you can consolidate multiple endpoints into a single OpenAPI file, that’s automatically pushed to SwaggerHub, the design and documentation platform, where you can further edit the documentation, generate client SDKs, create interactive documentation, and more!
Easily Parse and Test OpenAPI Endpoints
Developers are constantly required to double check if their APIs and endpoints work as intended during the development process. No one likes new processes, especially developers.
For developers working with APIs already defined in OpenAPI, Swagger Inspector provides an easy way to parse an OpenAPI 3.0 file, see the various endpoints and methods in the entire API, enabling them to pick the resource you want to test.
Simply insert the location of the API definition, or upload an OpenAPI file. For example, here’s where the SmartBear Petstore API defined in OAS 3.0 is located on SwaggerHub. Just insert thislocation into Inspector, and hit SEND. If it’s a valid OpenAPI 3.0 definition, you can see all the endpoints in the API with the USE DEFINITION button.
From here on, you can select the endpoint and method you want to validate and see if the responses match your expectations!
Finally, just go ahead and select the endpoints you just tested over in your history tab. From there, click on the “CREATE API DEFINITION” drop down and select OAS 3.0. You’ll need to create an account in order to complete your definition generation.
When we say we know OpenAPI, we mean it. The OAS is the best open standard to drive and accelerate your API development, and we hope Swagger Inspector can provide you with an easy way to get started with the OAS 3.0 specification.
Thanks for reading! Looking for more API resources? Subscribe to the Swagger newsletter. Receive a monthly email with our best API articles, trainings, tutorials, and more. Subscribe