抠丁客 抠丁客
项目
编辑 (2025/12/24)

Swagger 集成

Swagger (OpenAPI) 是一种用于描述 REST API 的与语言无关的规范。它允许计算机和人类在不直接访问源代码的情况下理解 REST API 的功能。其主要目标是：

  • 最小化连接解耦服务所需的工作量。
  • 减少准确记录服务所需的时间。

ABP 提供了一个预构建模块，只需少量配置即可实现完整的 Swagger 集成。

安装

此包已在启动模板中默认安装。因此，在大多数情况下，您不需要手动安装。

如果需要安装，建议使用 ABP CLI 来安装此包。

使用 ABP CLI

在 Web 或 HttpApi.Host 项目的文件夹（.csproj 文件所在目录）中打开命令行窗口，并键入以下命令：

abp add-package Volo.Abp.Swashbuckle

如果您尚未安装 ABP CLI，则需要先安装它。有关其他安装选项，请参阅 包描述页面。

手动安装

如果您想手动安装：

  1. 将 Volo.Abp.Swashbuckle NuGet 包添加到您的 Web 或 HttpApi.Host 项目中：

    dotnet add package Volo.Abp.Swashbuckle

  2. 将 AbpSwashbuckleModule 添加到模块的依赖项列表中：

    [DependsOn(
    //...其他依赖项
    typeof(AbpSwashbuckleModule) // <-- 像这样添加模块依赖
    )]
public class YourModule : AbpModule
{
}

配置

首先，我们需要在模块的 ConfigureServices 方法中使用 AddAbpSwaggerGen 扩展方法来配置 Swagger：

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

    //... 其他配置。

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

然后，我们可以在模块的 OnApplicationInitialization 方法中调用 UseAbpSwaggerUI 方法来使用 Swagger UI：

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

    //... 其他配置。

    app.UseStaticFiles();

    app.UseSwagger();

    app.UseAbpSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API");
    });
    
    //... 其他配置。
}

在 Swagger UI 上隐藏 ABP 端点

如果您想在 Swagger UI 上隐藏 ABP 的默认端点，请在 Swagger 配置中调用 HideAbpEndpoints 方法，如下例所示：

services.AddAbpSwaggerGen(
    options => 
    {
        //... 其他选项
        
        //在 Swagger UI 上隐藏 ABP 相关端点
        options.HideAbpEndpoints();
    }
)

结合 OAUTH 使用 Swagger

对于非 MVC/分层应用程序，我们需要使用 OAUTH 配置 Swagger 来处理授权。

ABP 默认使用 OpenIddict。要获取有关 OpenIddict 的更多信息，请查看此 文档。

为此，我们需要在模块的 ConfigureServices 方法中使用 AddAbpSwaggerGenWithOAuth 扩展方法，配合 OAuth 颁发者和作用域来配置 Swagger：

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

    //... 其他配置。

    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);
        }
    );
}

然后，我们可以在模块的 OnApplicationInitialization 方法中调用 UseAbpSwaggerUI 方法来使用 Swagger UI：

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

    //... 其他配置。

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

        var configuration = context.ServiceProvider.GetRequiredService<IConfiguration>();
        options.OAuthClientId("Test_Swagger"); // 客户端ID
        options.OAuthClientSecret("1q2w3e*");  // 客户端密钥
    });
    
    //... 其他配置。
}

不要忘记设置 OAuthClientId 和 OAuthClientSecret。

结合 OIDC 使用 Swagger

您可能还希望使用 OpenIdConnect 而不是 OAUTH 来配置 Swagger。当您需要配置与颁发者不同的元数据地址时（例如，将应用程序部署到 Kubernetes 集群或 Docker 时），这尤其有用。在这些情况下，登录过程将使用元数据地址来访问可通过互联网到达的有效身份验证服务器发现端点，并使用内部网络来验证获得的令牌。

为此，我们需要在模块的 ConfigureServices 方法中使用 AddAbpSwaggerGenWithOidc 扩展方法，配合 OAuth 颁发者和作用域来配置 Swagger：

context.Services.AddAbpSwaggerGenWithOidc(
    configuration["AuthServer:Authority"],
    scopes: new[] { "SwaggerDemo" },
    // "authorization_code"
    flows: new[] { AbpSwaggerOidcFlows.AuthorizationCode },
    // 部署在 K8s 上时，应是通过互联网可访问的 DNS 的元数据 URL，例如 https://myauthserver.company.com
    discoveryEndpoint: configuration["AuthServer:Authority"],
    options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "SwaggerDemo API", Version = "v1" });
        options.DocInclusionPredicate((docName, description) => true);
        options.CustomSchemaIds(type => type.FullName);
    });

flows 是 oidc-provider（身份验证服务器）支持的一系列默认 OIDC 流程。您可以在下面看到默认支持的流程：

  • AbpSwaggerOidcFlows.AuthorizationCode: "authorization_code" 流程是 默认且建议的 流程。即使有客户端密钥字段，也不需要客户端密钥。
  • AbpSwaggerOidcFlows.Implicit: 已弃用的 "implicit" 流程，过去用于 JavaScript 应用程序。
  • AbpSwaggerOidcFlows.Password: 传统的 password 流程，也称为资源所有者密码凭据流程。您需要为其提供用户名、密码和客户端密钥。
  • AbpSwaggerOidcFlows.ClientCredentials: 用于服务器到服务器交互的 "client_credentials" 流程。

您可以定义一个或多个流程，这些流程将显示在授权模式窗口中。您可以将其设置为 null，这将使用默认的 "authorization_code" 流程。

discoveryEndpoint 是用于 .well-known/openid-configuration 的、可通过互联网访问的 OpenID 提供者端点。您可以将其设置为 null，这将使用默认的 AuthServer:Authority 应用程序设置配置。如果您将应用程序部署到 Kubernetes 集群或 Docker Swarm，应将 discoveryEndpoint 设置为应可通过互联网访问的真实 DNS。

如果在显示授权模式窗口时遇到问题，请检查浏览器控制台日志，并确保您设置了正确且可访问的 discoveryEndpoint。

在本文档中