Since the release of the new OpenAPI Specification last July, we have gotten a lot of questions about how to easily convert existing APIs to the latest version of the specification, OpenAPI Specification 3.0 (OAS 3.0).
Last week, we hosted a free training: Migrating to OpenAPI 3.0: How to Convert Your Existing APIs with Swagger Tools. During the webinar, we covered the new features and improvements in OAS 3.0, and looked at a few options for how Swagger tools help convert your APIs to OAS 3.0.
Below is a recap of some of the tools that were covered during the webinar, and some frequently asked questions from attendees:
Tools for Getting Started with OpenAPI Specification 3.0
SwaggerHub Maven Plugin
This open source plugin can be extremely useful for users looking to update to OAS 3.0. It’s a simple maven plugin to access SwaggerHub hosting of OpenAPI/Swagger from a maven build process, primarily to integrate with other OpenAPI/Swagger maven tooling. One important consideration for using the plugin is that it exclusively supports Java-based APIs.
Learn more about the Maven Plugin
Swagger Inspector
Swagger Inspector is the newest addition to the Swagger toolkit. It’s an easy to use, browser-based API testing tool. This tool allows you to quickly validate endpoints for any API and then generate OAS 3.0 definitions and documentation from those endpoints you just tested. Unlike the SwaggerHub Maven plugin, Swagger Inspector allows you to test APIs in any language.
Learn more about Swagger Inspector
SwaggerHub
SwaggerHub is an API design and documentation platform, built for teams to drive consistency and discipline across the API development workflow. There are a lot of great features to highlight in SwaggerHub, but in this webinar we covered the 2.0 to 3.0 converting feature. The OpenAPI 2.0 to 3.0 converter lets you quickly convert your existing OpenAPI 2.0 definitions without having to update them manually. We also offer templates to create new definitions in OAS 3.0 if you’re interested in building from scratch.
Learn more about SwaggerHub
Frequently Asked Questions from the Webinar
More than 400 people tuned in to learn more about OAS 3.0 support in Swagger tools. We received a ton of questions during the session and weren’t able to answer them all. Below is a recap of the most frequently asked questions:
Are Swagger tools, like SwaggerHub and Swagger Inspector, free to use?
There are free versions of all Swagger tools, and we maintain 14+ open source tools for working with OAS APIs.
Swagger Inspector is a completely free tool. You can test and validate as many endpoints that you want with Swagger Inspector. Your free account lets you log your history of tests and curate pins and collections. You can access these tests from anywhere at any time.
SwaggerHub offers a free plan for individuals and small projects. We also offer paid tiers for organizations that need to collaborate on their API development, or use some of the pro capabilities of SwaggerHub, including the tools for governance and reusability.
Do you need to have a SwaggerHub account to use Swagger Inspector?
SwaggerHub and Swagger Inspector have a shared login, but you do not need to use both tools for all the tasks you need to get done. You don’t need to use SwaggerHub if you’re just using Swagger Inspector to test your APIs. You will however need to use SwaggerHub if you plan on generating definitions, hosting or iterating on your API.
What are the benefits of using the Swagger Maven Plugin vs Swagger Inspector?
Both Swagger Inspector and the Swagger Maven Plugin have beneficial use cases.
One advantage of the Swagger Maven Plugin is that it can be automated with CI/CD systems, However, as mentioned above, the Maven plugin only works for the Java language, whereas Swagger Inspector is available to use for APIs in any language.
A major benefit of Swagger Inspector is how quick it is to get started. OAS generation happens right from your API calls in Inspector, so the learning curve and setup is minimal. Swagger Inspector some times may generate incomplete definitions, where the Maven plugin can explicitly define OAS 3.0 to match the API. As you can see, both are great tools that can help you get to OAS 3.0 quickly.
What is the process for providing request/response definitions for complex object models? Does this have to be manually entered for all?
The reusable components feature in SwaggerHub – known as Domains – can help describe and reusable complex data models. You can define reusable structures (like responses) in a separate file called a domain for reuse in multiple APIs.
Learn more about Domains here.
Can you provide some real world (not Petstore) implementation examples of Swagger UI?
You can find plenty of examples of APIs published with the Swagger UI in the SwaggerHub API repository. You can search all public API projects and sort by OAS 2.0 and OAS 3.0.
There are also plenty of examples of companies that use Swagger UI for their public-facing documentation, including: Marvel and IBM.
Tools like Swagger Inspector and Swagger Core seem to cater toward a code first approach, isn’t it recommended to follow a design or definition-first approach?
We are seeing a growing number of organizations adopting a design-first approach, in which they start with writing the OAS definition before writing any code.
But we also understand that for a large percentage of organizations, making the transition to a design first approach can’t happen overnight, and these tools provide an alternative for getting started with OAS.
We typically see organizations doing a mix of code first and design first development with OAS. For existing APIs that were not built with design in mind, tools like Swagger Inspector make it quick and easy to generate an OAS definition that can be built out and used to further document your APIs.
Learn more about the different approaches to OAS
Where can I learn more about Swagger open source projects?
You can explore Swagger Open Source tools here. There are also repos for each of the Swagger projects on GitHub, which are actively maintained and continue to evolve, thanks to the work from the Swagger community.
Explore Swagger projects here.
Is it possible to import my existing OAS 3 definitions into SwaggerHub?
Yes, you can easily import any of your OAS 2.0 or OAS 2.0 definitions into SwaggerHub. Once imported into SwaggerHub, your OAS definition will be hosted within your organization and can be accessed by anyone that you invite to join your organization.
Learn more here.
Is there online documentation for a beginner to learn the OpenAPI Specification?
Yes, you can find documentation for OpenAPI Specification 3.0 here.
Here are some of our other favorite OAS 3.0 resources:
Hopefully if you attended the webinar and your question did not get answered, you found it here. As always, if there are ever any questions that you need answered, you can reach us in several ways: