.NET Core 3.1 集成 Swagger

最近工作上的变动，又开始拾起后端开发。

距离前面已经有两年多了。也是幸好当时已经对 .NET Core 有了一些了解，并且也开始了一些项目。

当时主要是基于 .NET Core 2.1 的。对比起来还是有了不少变化的。

就拿Swagger来说，在 2.1 当时还没有开源的库可以直接引用的。

Swagger 作为一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

对比以前为了给前端接口调用文档，是一个个在 Postman 上面测试调用，有了 Swagger 方便了很多。配置好后，在写代码时添加一些注释就可以使用。

一、注册

在注册 Swagger 前，先要引用所需的包：

Swashbuckle.AspNetCore

Swashbuckle.AspNetCore.Filters

安装完成后在 Startup.cs 文件中添加如下代码

public void ConfigureServices(IServiceCollection services)
{
            services.AddSwaggerGen(c =>
            {
                // 定义文档（可以多个）
                c.SwaggerDoc("V1", new OpenApiInfo { Title = "Backend.WebAPI", Version = "V1" });
                // 文档排序规则
                c.OrderActionsBy(o => o.RelativePath);
            });
}    

上面的代码是注册了 Swagger 生成器。我们想在运行时看到对应界面的话还需要添加对应的 UI 中间件：

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseHsts();
            }

            // 插入中间件，将生成的 Swagger 公开为 JSON 端点
            app.UseSwagger();
            // 插入 swagger-ui 中间件，公开交互式文档
            // 调用是： ip/port/swagger/index.html
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/V1/swagger.json", "Backend.WebAPI V1");

                // 路径配置，设置为空，直接在根域名下访问，这时 launchSettings 下面的 launchUrl 配置也改为空
                c.RoutePrefix = "";
            });

        }

二、注释信息

上面的配置完成后虽然可以看到 Swagger 文档界面，但是对应的接口注释都没有，不利于查看。

这时就需要对做两部分内容。

1、项目配置生成注释 xml 文件

一般要生成的注释主要有：接口、DTO

那就主要对着两个项目设置：对应项目右键=》属性=》生成 tab 页

如下图：

　　a、勾选“输出”下的“XML文档文件”，勾选后需要设置路径，路径使用“..XXXYYY”（..是相对目录，相对当前项目）

　　b、在“取消显示告警”后面输入框中添加：1591（用 ; 分隔）。不添加的话，多有当前项目下文件都需要注释，否则会有警告提示（根据个人喜好，我不喜欢有太多提示）

在当前解决方案中对需要的项目进行设置即可。

2、在代码中加载 xml 文件

已经生成了 xml 文件，需要在 Swagger 生成器中加载才可以在文档中看到，代码如下：

var basePath = ApplicationEnvironment.ApplicationBasePath;
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("V1", new OpenApiInfo { Title = "Backend.WebAPI", Version = "V1" });
    c.OrderActionsBy(o => o.RelativePath);

    // 加载 Control 配置信息
    var xmlPath = Path.Combine(basePath, "Backend.WebAPI.xml");
    c.IncludeXmlComments(xmlPath, true);

    // 加载 Model 配置信息
    var xmlModelPath = Path.Combine(basePath, "Backend.Model.xml");
    c.IncludeXmlComments(xmlModelPath, true);
});

我这里是添加了两个 xml 文件。

三、添加请求头

在项目中，添加了授权认证后。在 Swagger 上面测试接口，那么也需要带上 token 之类的。

这是还需要对进行配置：

var basePath = ApplicationEnvironment.ApplicationBasePath;
// 注册 Swagger 生成器，并定义文档（可以多个）
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("V1", new OpenApiInfo { Title = "Backend.WebAPI", Version = "V1" });
    c.OrderActionsBy(o => o.RelativePath);

    // 加载 Control 配置信息
    var xmlPath = Path.Combine(basePath, "Backend.WebAPI.xml");
    c.IncludeXmlComments(xmlPath, true);

    // 加载 Model 配置信息
    var xmlModelPath = Path.Combine(basePath, "Backend.Model.xml");
    c.IncludeXmlComments(xmlModelPath, true);

    // 使用 Filter 扩展 Swagger 生成器
    // 没有下面这几个 Filter， Swagger 上无法携带 Bearer ，接口就一直报错
    c.OperationFilter<AddResponseHeadersFilter>();
    c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
    c.OperationFilter<SecurityRequirementsOperationFilter>();

    // Token 绑定到 ConfigureServices
    c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Description = "JWT 授权，在下框中输入 Bearer {token}",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    });
});

配置完成后，在 Swagger UI 文档中会有需要输入 Authorize 的按钮。

整体配置完成后如下图：