(C# ASP.NET Core) OpenAPI and Swagger for Web API Documentation

Difference between Swagger and OpenApi

Let us quickly have a look a the difference between OpenApi and Swagger.

OpenApi is the specification that lays down the rules for describing the WebApi. It lays down the rules for documenting parameters, for documenting the responses, and so on. The rules have been described using XML.

Swagger, on the other hand, refers to the software tools and applications that implement the above specification. Some of these tools generate intermediate documents such as "openapi.json", while there are yet others that use these intermediate documents to render the API in a well-formatted GUI based interface. Examples of such applications are SwaggerUI and OpenAPIGenerator. We shall talk more about SwaggerUI later in this tutorial.

Many developers use the two terms interchangeably - OpenApi and Swagger are used interchangeably in day to day life. These terms together refer to the applications that generate the documentation, and to those that present them, and to the rules that are used to generate the documentation.

Video Explanation (see it happen!)

Please watch the following youtube video:

What are SwashBuckle and NSwag

SwashBuckle and NSwag are two main DOTNET implementations of the OpenApi (or Swagger) specification.

Both of them include a web-based UI called SwaggerUI. You may have already heard of that in the past.

As an ASPNET Core developer we do not have to worry about the finer details of SwashBuckle and NSwag because everything is handled for us by the ASPNET Core Engine. The only thing we need to do is to configure the middleware correctly!

You will need the following nuget package for SwashBuckle: Install-Package Swashbuckle.AspNetCore

Install-Package Swashbuckle.AspNetCore 

We shall explain the process in the next tutorial. Thanks!