Swagger 是一个用于构建、文档化和测试 RESTful API 的开源框架，它可以自动生成 API 文档、提供在线调试界面等功能。在 ASP.NET Core 中，可以使用 Swagger 中间件来实现 API 文档的自动生成。在VS中创建API解决方案默认Swagger接口文档，但是接口文档UI都是默认的，对于中文不是很友好，默认不会现在每个接口的注释名称，下面我从默认配置和两个微调方式优化API文档。

、默认配置

在VS中新建创建API项目时候，启用OpenAPI支持即可默认增加Swagger文档支持。然后在项目文档中生成输出，包含生成的API文档的文件勾选上，如下图所示：

我们开发一个Action作为测试代码如下：

        /// <summary>
        /// 获取天气.
        /// </summary>
        /// <returns></returns>
        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }

结果展示：

文档虽然显示相关接口，但是未按我们期望的注释作为名称展示。下面我们进行简单优化，让其符合我们预期期望。

2、SwaggerOperation 增加注释

SwaggerOperation 是一个有用的属性，您可以在其中设置单个请求/路由的摘要、描述、ID 和标签。

首先引入
Swashbuckle.AspNetCore.Annotations包，然后我们需要在Program.cs 启用注释，代码如下：

builder.Services.AddSwaggerGen(c =>
{
    c.EnableAnnotations();
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Test API", Version = "v1" });
});

我们只在原理代码增加c.EnableAnnotations(); 开启注释。然后我们最后我们调整API接口。使用SwaggerOperation进行注释标记。

/// <summary>
        /// 获取天气.
        /// </summary>
        /// <returns></returns>
        [HttpGet(Name = "GetWeatherForecast")]
        [SwaggerOperation(Summary = "获取天气接口", Description = "获取天气")]
        [SwaggerResponse(StatusCodes.Status200OK, "OK", typeof(IEnumerable<WeatherForecast>))]
        [SwaggerResponse(StatusCodes.Status404NotFound, "Not Found")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }

现在我们查看下实例结果，下图显示了摘要和说明在 swagger UI 文档中的显示方式：

3、统一配置自定义CustomOperationIds

SwaggerOperation 增加注释需要在每个接口自定义，设想采用统一方式，不额外增加代码，实现注释作为API文档名称。我们先包含所有的XML文档输出文件，然后自定义CustomOperationIds 扩展Swagger的OperationId。代码如下：

builder.Services.AddSwaggerGen(c =>
{
    //c.EnableAnnotations();
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Test API", Version = "v1" });
    var basePath = PlatformServices.Default.Application.ApplicationBasePath;
    foreach (var xmlFile in Directory.GetFiles(basePath, "*.xml"))
    {
        //包含控制器 Xml 注释
        c.IncludeXmlComments(xmlFile, true);
    }

    // 自定义菜单ID
    c.CustomOperationIds(apiDesc =>
    {
        var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
        return controllerAction.ControllerName + "-" + controllerAction.ActionName;
    });

    c.UseInlineDefinitionsForEnums();
});

这样API Action只需要简单注释。如下所示：

/// <summary>
        /// 获取天气.
        /// </summary>
        /// <returns></returns>
        [HttpGet(Name = "GetWeatherForecast")]
        //[SwaggerOperation(Summary = "获取天气接口", Description = "获取天气")]
        //[SwaggerResponse(StatusCodes.Status200OK, "OK", typeof(IEnumerable<WeatherForecast>))]
        //[SwaggerResponse(StatusCodes.Status404NotFound, "Not Found")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }

下图显示了不同状态代码的 SwaggerResponse 如何在 swagger UI 文档中显示：

虽然第三种方式不如第二种方式内容多，但是不需要额外对每个Action 增加特性标记，只需要写相关注释即可。

总结

综上所述，使用 Swagger 中间件可以方便地实现 ASP.NET Core 应用的 API 文档自动生成和在线调试功能。只需要安装 Swashbuckle.AspNetCore 包，配置 Swagger 中间件，生成 API 文档，然后就可以通过访问 /swagger 终端点来查看 API 文档。同时也可以通过特性来自定义 Swagger 文档。如上两种方式非常适合中文习惯。当然最好使用UseKnife4UI 进行文档展示效果更佳。

欢迎大家对Swagger文档有使用过程中有什么好的想法或者什么问题，欢迎大家一起学习，留言板见，谢谢。