Swagger Integration

Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Its main goals are to:

  • Minimize the amount of work needed to connect decoupled services.
  • Reduce the amount of time needed to accurately document a service.

ABP Framework offers a prebuilt module for full Swagger integration with small configurations.

Installation

This package is already installed by default with the startup template. So, most of the time, you don't need to install it manually.

If installation is needed, it is suggested to use the ABP CLI to install this package.

Using the ABP CLI

Open a command line window in the folder of the Web or HttpApi.Host project (.csproj file) and type the following command:

abp add-package Volo.Abp.Swashbuckle

Manual Installation

If you want to manually install;

  1. Add the Volo.Abp.Swashbuckle NuGet package to your Web or HttpApi.Host project:

    Install-Package Volo.Abp.Swashbuckle

  2. Add the AbpSwashbuckleModule to the dependency list of your module:

    [DependsOn(
        //...other dependencies
        typeof(AbpSwashbuckleModule) // <-- Add module dependency like that
        )]
    public class YourModule : AbpModule
    {
    }
    

Configuration

First, we need to use AddAbpSwaggerGen extension to configure Swagger in ConfigureServices method of our module.

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var services = contex.Services;

    //... other configarations.

    services.AddAbpSwaggerGen(
        options =>
        {
            options.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "v1" });
            options.DocInclusionPredicate((docName, description) => true);
            options.CustomSchemaIds(type => type.FullName);
        }
    );
}

Then we can use Swagger UI by calling UseAbpSwaggerUI method in the OnApplicationInitialization method of our module.

public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    var app = context.GetApplicationBuilder();

    //... other configarations.

    app.UseAbpSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API");
    });
    
    //... other configarations.
}

Using Swagger with OAUTH

For non MVC/Tiered applications, we need to configure Swagger with OAUTH to handle authorization.

ABP Framework uses IdentityServer by default. To get more information about IDS, check this documentation.

To do that, we need to use AddAbpSwaggerGenWithOAuth extension to configure Swagger with OAuth issuer and scopes in ConfigureServices method of our module.

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var services = contex.Services;

    //... other configarations.

    services.AddAbpSwaggerGenWithOAuth(
        "https://localhost:44341",             // authority issuer
        new Dictionary<string, string>         //
        {                                      // scopes
            {"Test", "Test API"}               //
        },                                     //
        options =>
        {
            options.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "v1" });
            options.DocInclusionPredicate((docName, description) => true);
            options.CustomSchemaIds(type => type.FullName);
        }
    );
}

Then we can use Swagger UI by calling UseAbpSwaggerUI method in the OnApplicationInitialization method of our module.

Do not forget to set OAuthClientId and OAuthClientSecret.

public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    var app = context.GetApplicationBuilder();

    //... other configarations.

    app.UseAbpSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API");

        var configuration = context.ServiceProvider.GetRequiredService<IConfiguration>();
        options.OAuthClientId("Test_Swagger"); // clientId
        options.OAuthClientSecret("1q2w3e*");  // clientSecret
    });
    
    //... other configarations.
}

Contributors


Last updated: September 30, 2021 Edit this page on GitHub

Was this page helpful?

Please make a selection.

To help us improve, please share your reason for the negative feedback in the field below.

Please enter a note.

Thank you for your valuable feedback!

Please note that although we cannot respond to feedback, our team will use your comments to improve the experience.

In this document
Community Talks

Building Modular Monolith Applications Using .Net and ABP Framework

17 Oct, 20:00
Online
Register Now
Mastering ABP Framework Book
Mastering ABP Framework

This book will help you gain a complete understanding of the framework and modern web application development techniques.

Learn More