.net core 6.0 Web API Swagger接口文档添加注释和版本控制

微软官网文档地址：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-6.0&tabs=visual-studio

一、接口注释

1、在控制器和方法上面添加类似下面的注释

        /// <summary>
        /// 获取天气
        /// </summary>
        /// <returns></returns>

2、添加GenerateDocumentationFile， 有两种方式

（1）方式一：右键项目--选择属性，然后找到生成包含API文档的文件并勾选（如下图）

DC6EF753825DAF7A73F011100E882985.png

（2）方式二：右键项目 -- 编辑项目文件，然后在PropertyGroup中直接添加键 GenerateDocumentationFile，值为 True

  <PropertyGroup>
    <GenerateDocumentationFile>True</GenerateDocumentationFile>
  </PropertyGroup>

3、在 Program.cs 中找到builder.Services.AddSwaggerGen();，直接替换为下面代码，运行工程即可

builder.Services.AddSwaggerGen(options => {
    // 注释
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    // 第二个参数为是否显示控制器注释,我们选择true
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), true);
    // 生成多个文档显示
    typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
    {
        //添加文档介绍
        options.SwaggerDoc(version, new OpenApiInfo
        {
            Title = $"项目名",
            Version = version,
            Description = $"项目名:{version}版本"
        });
    });
});

二、版本控制

1、创建一个枚举类

/// <summary>
/// Api版本枚举类
/// </summary>
public enum ApiVersions
{
    /// <summary>
    /// 版本V1
    /// </summary>
    V1 = 1,
    /// <summary>
    /// 版本V2
    /// </summary>
    V2 = 2
}

2、在 Program.cs 中找到builder.Services.AddSwaggerGen();，添加替换为如下代码

builder.Services.AddSwaggerGen(options =>
{
    // 生成多个文档显示
    typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
    {
        // 添加文档介绍
        options.SwaggerDoc(version, new OpenApiInfo
        {
            Title = $"项目名",
            Version = version,
            Description = $"项目名:{version}版本"
        });
    });
});

3、在 Program.cs 中找到builder.Services.UseSwaggerUI();，替换为如下代码

    app.UseSwaggerUI(options =>
    {
        //options.SwaggerEndpoint($"/swagger/V1/swagger.json", $"版本选择:V1");
        //如果只有一个版本也要和上方保持一致
        typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
        {
            //切换版本操作
            //参数一是使用的哪个json文件,参数二就是个名字
            options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"版本选择:{version}");
        });
    });

4、在对应方法上添加[ApiExplorerSettings(GroupName = "V1")]，然后运行工程即可

        /// <summary>
        /// 获取天气
        /// </summary>
        /// <returns></returns>
        [ApiExplorerSettings(GroupName = "V1")]
        [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();
        }

        /// <summary>
        /// 获取天气版本2
        /// </summary>
        /// <returns></returns>
        [ApiExplorerSettings(GroupName = "V2")]
        [HttpGet]
        [Route("~/GetWeatherForecast2")]
        public IEnumerable<WeatherForecast> Get2()
        {
            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.png