Swagger Configuration for Asp.Net Core projects

Package installation

Swashbuckle can be added with the following approaches:

• From the Package Manager Console window:
  • Go to View > Other Windows > Package Manager Console
  • Navigate to the directory in which the TodoApi.csproj file exists
  • Execute the following command:
    PowerShell

    Install-Package Swashbuckle.AspNetCore
    

• From the Manage NuGet Packages dialog:
• Right-click the project in Solution Explorer > Manage NuGet Packages
• Set the Package source to "nuget.org"
• Enter "Swashbuckle.AspNetCore" in the search box
• Select the "Swashbuckle.AspNetCore" package from the Browse tab and click Install

Add and configure Swagger middleware

Add the Swagger generator to the services collection in the Startup.ConfigureServices method:

C#

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });
}

Import the following namespace to use the Info class:

C#

using Swashbuckle.AspNetCore.Swagger;

In the Startup.Configure method, enable the middleware for serving the generated JSON document and the Swagger UI:

C#

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseMvc();
}

The preceding UseSwaggerUI method call enables the Static Files Middleware. If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.

Launch the app, and navigate to http://localhost:/swagger/v1/swagger.json. The generated document describing the endpoints appears as shown in Swagger specification (swagger.json).

The Swagger UI can be found at http://localhost:/swagger. Explore the API via Swagger UI and incorporate it in other programs.


Tip

To serve the Swagger UI at the app's root (http://localhost:/), set the RoutePrefix property to an empty string:

C#
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});


Customize and extend

Swagger provides options for documenting the object model and customizing the UI to match your theme.

API info and description

The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:

C#
// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = "None",
        Contact = new Contact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        },
        License = new License
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        }
    });
});


The Swagger UI displays the version's information:







Source: https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.1&tabs=visual-studio%2Cvisual-studio-xml