How to generate API documentation in Open API 2.0 with SwashBuckle 5.0 and above?

Hello everyone and welcome to my blog. In today’s blog, I shall walk you through on how to generate Open API 2.0 Swagger.json using Swashbuckle 5.0 and above.

If you are not aware of SwashBuckle, Swashbuckle is an open source project for generating Swagger documents for Web APIs that are built with ASP.NET Core. If you want to learn more, you can visit this Microsoft learn link.

With SwashBuckle 5.0 and above, the generated Swagger.json is OpenAPI 3.0 compliant. However there many scenarios where platforms still need Open API 2.0 to integrate.

For example – If you want to create a custom connector from an Open API documentation, it need to be complaint with Open API 2.0.

One way to accomplish this is downgrade SwashBuckle version to 4.0 or below. However that is not the ideal way since you loose out on the benefits of using higher version. In .NET core Web API, we use the below code to configure generate Swagger using Swashbuckle.

The critical line here is app.UseSwagger. We need to overload the UseSwagger function to generate api documentation using Open API 2.0. 

app.UseSwagger(p=> p.SerializeAsV2 = true);

When you run the flow and navigate to the Swagger URL, the downloaded Swagger.json shall be API 2.0 compliant.

Small tip but can save hours if you get stuck with the issue.

Hope you liked this post. If this post has helped, you can buy me a coffee. Links on right pane.

For similar topics on Microsoft.NET and Power Platform, subscribe to my blog using the Subscribe option on right pane.

You will also like the below posts.

Debajit Dutta
Business Solutions MVP