A while back I wrote an OSS Spotlight post about the Swagger project. In short, Swagger is “the world’s most popular API tooling”. It’s a powerful open source framework backed by a very large ecosystem of tools that help you design, build, document, and consume your RESTful APIs. The Swagger v3.0 Specification was contributed to the OpenAPI Initiative, and thus Swagger has been merged with OpenAPI. Basically, Swagger is now OpenAPI.

Briefly What was Swagger?

Swagger is a powerful open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs. The way that Swagger works, is that you “swagger-enable” your API. In .NET you can do this by including a Nuget package called Swashbuckle. This will autogenerate a Swagger definition file (in JSON format) for your API that is easily accessible at a URL on your API’s site. Then you can use code generation tools to read this Swagger definition file and auto-generate client SDK code in any of the huge list of supported languages.

Swagger not only auto-generates the definition file and client SDK’s but it also auto-generates a UI to be able to discover and test out your APIs as well. This is done using the Swagger UI. See the below screenshot for an example of what it looks like:

If you want to see what the Swagger UI looks like in more detail and try it out for yourself, here’s a live demo: http://petstore.swagger.io

What is OpenAPI and the Open API Initiative?

Here’s a quote from the http://openapis.org website that states what the OpenAPI Initiative is:

The Open API Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. SmartBear Software is donating the Swagger Specification directly to the OAI as the basis of this Open Specification. APIs form the connecting glue between modern applications. Nearly every application uses APIs to connect with corporate data sources, third party data services or other applications. Creating an open description format for API services that is vendor neutral, portable and open is critical to accelerating the vision of a truly connected world.

Basically, OpenAPI is a larger initiative that just a single Open Source project. While Swagger made a lot of progress towards the effort, the fact that Swagger has essentially joined the OpenAPI Initiative is a good move to consolidate it with the rest of the overall initiatives of OpenAPI. As a result, the last version of the Swagger Specification is v2.0, and the first OpenAPI Specification is version 3.0.

Don’t worry, the Swagger project isn’t going away, as it’s been merged with OpenAPI. You can still call it Swagger, but it can now be referred to as OpenAPI. Also, there are some tools that use Swagger that have already renamed it in the UI and documentation as OpenAPI; such as Microsoft Azure API Management. So, don’t be confused when you see either name in UI and documentation; just remember that Swagger is the old name and OpenAPI is pretty much the new name, but the specification is the same specification you’re expecting.

Happy building, consuming, and sharing APIs!

About the Author

Chris Pietschmann

Chris Pietschmann is a Microsoft MVP, HashiCorp Ambassador, and Microsoft Certified Trainer (MCT) with 20+ years of experience designing and building Cloud & Enterprise systems. He has worked with companies of all sizes from startups to large enterprises. He has a passion for technology and sharing what he learns with others to help enable them to learn faster and be more productive.