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!

 

Posted by Chris Pietschmann

Chris is a Microsoft MVP and has nearly 20 years of experience building enterprise systems both in the cloud and on-premises. He is also a Certified Azure Solutions Architect (both MCSD and MCSE), a trainer, and Cloud Advocate. He has a passion for technology and sharing what he learns with others to help enable them to learn faster and be more productive.

8 Comments

  1. […] Swagger is now the OpenAPI Specification (Chris Pietschmann) […]

    Reply

    1. Uhhh, it “is” or it “has” an Open API Specification?

      If you say it is, then Swagger replaces the previous Open API Specification and that just is strange. In any case, the title of this article is misleading.

      Reply

    1. Chris Pietschmann October 23, 2017 at 1:24 pm

      It was still mostly called Swagger until recently.

      Reply

  2. Hmm. Ok 🤔

    Reply

    1. Chris Pietschmann October 23, 2017 at 1:28 pm

      It also isn’t very well known

      Reply

  3. I knew it.

    Reply

  4. Just a few clarifications.

    At the beginning of the article you mention “The Swagger v3.0 Specification was contributed to the OpenAPI Initiative” – It was Swgger v2.0 that was contributed, not 3.0.

    Swagger has not been merged with the OpenAPI. These days, the name “Swagger” is used for a specific toolset (swagger.io) around the OpenAPI specification, whereas the OpenAPI is the specification only and does not contain any tooling. The former is maintained by SmartBear whereas the latter is governed by the Open API Initiative under the Linux Foundation.

    Even the Swagger 2.0 specification has been re-released as the OpenAPI 2.0 specification, with no technical changes. These days, especially after the release of OAS3, it is not correct to use the term Swagger in reference to the specification or an API document based on the specification. We understand and appreciate that such a naming transition takes time, but prefer to clarify it when possible.

    Reply

Leave a Reply