How To Implement Swagger In ASP.NET Core Web API

Introduction

 

Swagger (Open API) is a language-agnostic specification for describing and documenting the REST API. Swagger allows both the machine and developer to understand the working and capabilities of the machine without direct access to the source code of the project. The main objectives of swagger (Open API) are to,

• Minimize the workload to connect with Microservice.
• Reduce the time needed to accurately document the Microservice.

OpenAPI Implementation Process

 

There are two main implementations of open API For Asp.net Core technologies, like using Swashbuckle and NSwag. I will discuss both one by one in separate articles.

 

OpenAPI vs Swagger

 

Open API Refers to the specification and Swagger refers to the family of the open-source and commercial products from SmartBear that work with the OpenAPI Specification. Subsequent Open-source products such as OpenAPIGenerator also fall under the category of Swagger.

 

In short,

• OpenAPI is Specification
• Swagger is the tool the uses OpenAPI Specification for Example OpenAPIGenerator and Swagger UI.

OpenAPI Specification 

 

The OpenAPI Specification is a document that describes the capabilities of our APIs. The Open Specification is based on XML and attributes annotations with the controller and models. It is the main part of the OpenAPI flow and is used to drive the tools such as SwaggerUI by Default. Its name is openapi.json. The given below Jason file is the example of the OpenAPI Specification.

{
  "openapi": "3.0.4",
  "info": {
    "title": "API V3",
    "version": "v3"
  },
  "paths": {
    "/api/GetPayment": {
      "get": {
        "tags": [
          "GetPayment"
        ],
        "operationId": "ApiGetPayment",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GetPayment"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GetPayment"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GetPayment"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/GetPayment/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger UI

 

Swagger UI (User Interface) is the web-based UI that provides information about the microservice using the generated Open API Specification. Both Swashbuckle and NSwag include an embedded version of Swagger UI so that it can be hosted in your ASP.NET Core App using a middleware component called the web. The UI Of Swagger looks like below.

 

Figure 1.1

 

Figure 1.2

 

 

Figure 1.3

 

Getting Started with Swashbuckle in ASP.NET Core

 

There are three main components of Swashbuckle.

 

Swashbuckle.AspNetCore.Swagger

 

Swashbuckle.AspNetCore.Swagger is the Object Model and Middleware to expose swagger Document as JSON End Points.

 

Swashbuckle.AspNetCore.SwaggerGen

 

A Swagger Generator that builds Swagger Document Objects Directly from your routes controllers and models, this package is combined with Swagger endpoints middleware to automatically expose the Swagger JSON.

 

Swashbuckle.AspNetCore.SwaggerUI

 

Swashbuckle.AspNetCore.SwaggerUI is an embedded version of the Swagger UI Tool. It explains swagger JSON to build a rich customizable practical for explaining the Web API functionality and  it includes a built-in test harnessed for the public Methods.

 

Package Installation

 

Package Installation Using Package Manager Console.

1. Go to the View> Other Windows > Package Manager Console
2. Execute the Command

Install-Package Swashbuckle.AspNetCore -version 5.6.3

 

 

 

Package Installation Using Nuget Package Library

 

Install the Package using the Nuget package Library

1. Right-click on the Project Solution Explorer and select the ManageNuget Packages
2. Set the Package source to Nuget.org.
3. Ensure the prerelease option is enabled.
4. Enter the Name of the package Swashbuckle.AspNetCore.
5. Select the latest version and hit the installation button.

 Figure 1.6

 

 

 Figure 1.7

 

Add and Configure the Middleware

 

Add the Middleware component to the startups class in the Startup.ConfigureServices of the project.

 

Startup.ConfigureServices

 

 

 Figure 1.8

 

Code of the project in Configure Services 

public void ConfigureServices(IServiceCollection services) {
    services.AddControllers();
    services.AddHttpClient();
    services.AddMvc();
    services.AddDbContext < ApplicationDbContext > (options => options.UseSqlServer(_configuration.GetConnectionString("DefaultConnection")));
    services.AddTransient < IRepository < Payment > , PaymentRepository > ();
    services.AddTransient < PaymentService, PaymentService > ();
    services.AddSwaggerGen();
}

Startup. Configure

 

 

Code of the Project in Configure Method 

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    if (env.IsDevelopment()) {
        app.UseDeveloperExceptionPage();
    }
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints => {
        endpoints.MapControllers();
    });
    app.UseSwagger();
    app.UseSwaggerUI(c => {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V2");
    });
  }
}

Summary

 

Swagger (Open API) is a language-agnostic specification for describing and documenting the REST API. Swagger allows both the machine and the developer to understand the working and capabilities of Machine without direct access to the source code of the project the main objectives of swagger (Open API) are to:

• Minimize the workload to connect with Microservice.
• Reduce the time needed to accurately document the Microservice.

Swagger is the Interface Description Language for Describing the RESTful APIs expressed using JSON. Swagger is used to gather a set of open-source software tools to design build documents and use Restful Web Services. Swagger includes automated documentation code generation.  Swashbuckle.AspNetCore.SwaggerUI is an embedded version of the Swagger UI Tool.

 

Conclusion

 

Swagger is the best Open API for documenting the Restful API. As a developer I have had a great experience with Swagger for testing the restful API sending the complete JSON Object and then getting the response in a professional way. It is easy to implement in Asp.net core Web API projects and after the configuration, developers can enjoy the beauty of Swagger Open API.