Asp .Net Core 系列：基于 Swashbuckle.AspNetCore 包集成 Swagger

什么是 Swagger?

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它提供了一种规范的方式来定义、构建和文档化 RESTful Web 服务，使客户端能够发现和理解各种服务的功能。Swagger 的目标是使部署管理和使用功能强大的 API 从未如此简单。

Swagger 提供了一种基于 YAML 或 JSON 格式的规范语言，用于描述 RESTful Web 服务的元数据，包括 API 的版本、资源、请求方法、参数、响应等信息。通过使用 Swagger 工具，开发人员可以生成 API 文档，并与可视化工具集成，提供了一个用户友好的界面来测试和使用 API。

此外，Swagger 还提供了一些额外的功能，如 API 的版本控制、认证和授权、API 的监控和度量等。这些功能可以帮助开发人员更好地管理和维护 RESTful Web 服务。

总之，Swagger 是一个强大的工具，可以帮助开发人员构建、文档化和使用 RESTful Web 服务，提高 API 的开发效率和管理水平。

什么是 Swashbuckle.AspNetCore？

Swashbuckle.AspNetCore 是一个开源的 .NET 包，用于为 ASP.NET Core Web API 生成美观的、交互式的 OpenAPI 文档（以前称为 Swagger）。它是一个强大的工具，可以帮助开发人员快速生成易于理解和使用的 API 文档。

官网：https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/README.md

Asp .Net Core 如何集成 Swagger?

要在 ASP.NET Core 项目中集成 Swashbuckle.AspNetCore，可以按照以下步骤进行操作：

安装 Swashbuckle.AspNetCore NuGet 包：

在 Visual Studio 中打开你的 ASP.NET Core 项目，并通过 NuGet 包管理器安装 Swashbuckle.AspNetCore 包。

Install-Package Swashbuckle.AspNetCore

配置 Swashbuckle.AspNetCore：
在 Startup.cs 文件的 ConfigureServices 方法中，注册 Swashbuckle 服务。

            builder.Services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "订单服务",
                    Version = "v2",
                    Description = "订单服务描述",
                    Contact = new OpenApiContact
                    {
                        Name = "robin",
                        Email = "2545233857@qq.com"
                    },
                    License = new OpenApiLicense
                    {
                        Name = "MIT",
                        Url = new Uri("https://www.cnblogs.com/vic-tory")
                    },
                });

                // 设置排序
                options.OrderActionsBy((apiDesc) => $"{apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.HttpMethod}");

                //设置
                var filePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "SwaggerDemo.xml");

                options.IncludeXmlComments(filePath);
            });

更改 Swagger JSON 端点的路径

默认情况下，Swagger JSON 将在以下路由中公开 - “/swagger/{documentName}/swagger.json”。如有必要，您可以在启用 Swagger 中间件时更改此设置。自定义路由必须包含该{documentName}参数。

app.UseSwagger(c =>
{
    c.RouteTemplate = "api-docs/{documentName}/swagger.json";
});

注意：如果您使用 SwaggerUI 中间件，您还需要更新其配置以反映新端点：

app.UseSwaggerUI(c =>
{
   c.RoutePrefix = "swagger"; //指定路由前缀
   c.SwaggerEndpoint("/api-docs/v1/swagger.json", "order api v1");
})

包含 XML 注释中的描述

为了通过人性化的描述来增强生成的文档，您可以使用 Xml 注释来注释控制器操作和模型，并配置 Swashbuckle 将这些注释合并到输出的 Swagger JSON 中：

打开项目的“属性”对话框，单击“构建”选项卡并确保选中“XML 文档文件”，或者将true元素添加到.csproj 项目文件的部分。这将在构建时生成一个包含所有 XML 注释的文件。

此时，任何未使用 XML 注释进行注释的类或方法都将触发构建警告。要抑制这种情况，请在属性对话框的“抑制警告”字段中输入警告代码“1591”，或添加1591到.csproj 项目文件的部分。

配置 Swashbuckle 将文件上的 XML 注释合并到生成的 Swagger JSON 中：

                var filePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "SwaggerDemo.xml");

                options.IncludeXmlComments(filePath);

方法上

        /// <summary>
        /// 获取天气
        /// </summary>
        /// <param name="param">参数</param>
        /// <returns>返回一个天气集合</returns>
        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable<WeatherForecast> Get(string param)
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }

添加 Jwt 验证

                options.AddSecurityDefinition("bearerAuth", new OpenApiSecurityScheme
                                                            {
                                                                Type = SecuritySchemeType.Http,
                                                                Scheme = "bearer",
                                                                BearerFormat = "JWT",
                                                                Description = "请输入Jwt 字符串"
                                                            });


                options.AddSecurityRequirement(new OpenApiSecurityRequirement
                                              {
                                                  {
                                                      new OpenApiSecurityScheme
                                                      {
                                                          Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "bearerAuth" }
                                                      },
                                                      new string[] {}
                                                  }
                                              });

第三方包

Package	Description
Swashbuckle.AspNetCore.Filters	Some useful Swashbuckle filters which add additional documentation, e.g. request and response examples, authorization information, etc. See its Readme for more details
Unchase.Swashbuckle.AspNetCore.Extensions	Some useful extensions (filters), which add additional documentation, e.g. hide PathItems for unaccepted roles, fix enums for client code generation, etc. See its Readme for more details
MicroElements.Swashbuckle.FluentValidation	Use FluentValidation rules instead of ComponentModel attributes to augment generated Swagger Schemas
MMLib.SwaggerForOcelot	Aggregate documentations over microservices directly on Ocelot API Gateway

封装 Swagger 扩展

SwaggerServiceExtensions

    /// <summary>
    /// Swagger 服务扩展
    /// </summary>
    public static class SwaggerServiceExtensions
    {
        /// <summary>
        /// 添加 Swagger 服务
        /// </summary>
        /// <param name="services"></param>
        /// <param name="swaggerOptions"></param>
        /// <returns></returns>
        public static IServiceCollection AddMCodeSwagger(this IServiceCollection services, SwaggerOptions swaggerOptions)
        {
            services.AddSingleton(swaggerOptions);

            SwaggerGenServiceCollectionExtensions.AddSwaggerGen(services, c =>
            {
                c.SwaggerDoc(swaggerOptions.ServiceName, swaggerOptions.ApiInfo);

                if (swaggerOptions.XmlCommentFiles != null)
                {
                    foreach (string xmlCommentFile in swaggerOptions.XmlCommentFiles)
                    {
                        string str = Path.Combine(AppContext.BaseDirectory, xmlCommentFile);
                        if (File.Exists(str)) c.IncludeXmlComments(str, true);
                    }
                }

                SwaggerGenOptionsExtensions.CustomSchemaIds(c, x => x.FullName);

                c.AddSecurityDefinition("bearerAuth", new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer",
                    BearerFormat = "JWT",
                    Description = "请输入 bearer 认证"
                });


                c.AddSecurityRequirement(new OpenApiSecurityRequirement
                                              {
                                                  {
                                                      new OpenApiSecurityScheme
                                                      {
                                                          Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "bearerAuth" }
                                                      },
                                                      new string[] {}
                                                  }
                                              });
            });

            return services;
        }

        /// <summary>
        /// 使用 Swagger UI
        /// </summary>
        /// <param name="app"></param>
        /// <returns></returns>
        public static IApplicationBuilder UseMCodeSwagger(this IApplicationBuilder app)
        {
            string serviceName = app.ApplicationServices.GetRequiredService<SwaggerOptions>().ServiceName;

            SwaggerUIBuilderExtensions.UseSwaggerUI(SwaggerBuilderExtensions.UseSwagger(app), c =>
            {
                c.SwaggerEndpoint("/swagger/" + serviceName + "/swagger.json", "api." + serviceName);
            });
            return app;
        }
    }

SwaggerOptions

    /// <summary>
    /// Swagger配置
    /// </summary>
    public class SwaggerOptions
    {
        /// <summary>
        /// 服务名称
        /// </summary>
        public string ServiceName { get; set; }

        /// <summary>
        /// API信息
        /// </summary>
        public OpenApiInfo ApiInfo { get; set; }

        /// <summary>
        /// Xml注释文件
        /// </summary>
        public string[] XmlCommentFiles { get; set; }

        /// <summary>
        /// 构造函数
        /// </summary>
        /// <param name="serviceName">服务名称</param>
        /// <param name="apiInfo">API信息</param>
        /// <param name="xmlCommentFiles">Xml注释文件</param>
        public SwaggerOptions(string serviceName, OpenApiInfo apiInfo, string[] xmlCommentFiles = null)
        {
            ServiceName = !string.IsNullOrWhiteSpace(serviceName) ? serviceName : throw new ArgumentException("serviceName parameter not config.");
            ApiInfo = apiInfo;
            XmlCommentFiles = xmlCommentFiles;
        }
    }