Swagger 版本控制 & 注释展示（.NET）

版本控制

项目创建

以Visual Studio 2022为例，创建Web API项目，如下图所示。

在创建时勾选启用OpenAPI支持，默认安装Swashbuckle.AspNetCore库，并配置相关信息。

创建版本枚举类

    /// <summary>
    /// 版本枚举
    /// </summary>
    public enum ApiVersions
    {
        /// <summary>
        /// 第一版本
        /// </summary>
        V1,

        /// <summary>
        /// 第二版本
        /// </summary>
        V2,

        /// <summary>
        /// 第三版本
        /// </summary>
        V3,
    }

修改 Program.cs 配置

builder.Services.AddSwaggerGen(option =>
{
    typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
    {
        option.SwaggerDoc(version, new OpenApiInfo()
        {
            Title = $"{version} Api文档",
            Version = version,
            Description = $"通用版本的CoreApi版本{version}"
        });
    });
});

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(option =>
    {
        foreach(string version in typeof(ApiVersions).GetEnumNames())
        {
            option.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"版本：{version}");
        }
    });
}

在 Controller 中配置

根据自己的需求，在不同的Controller中配置不同的版本。

//以V1为例
[ApiExplorerSettings(IgnoreApi = false, GroupName = nameof(ApiVersions.V1))]

效果展示

控制展示

项目配置

选择项目右键点击 -> 选择属性 -> 选择生成 -> 选择输出 -> 勾选生成包含API文档的文件。如下图所示

勾选之后进行保存，并将所选项目进行重新生成。

修改 Program.cs 配置

builder.Services.AddSwaggerGen(option =>
{
    //xml文档绝对路径 （项目名称按照实际情况填写）
    var file = Path.Combine(AppContext.BaseDirectory, "项目名称.xml");
    //true：显示控制器层注释
    option.IncludeXmlComments(file, true);
    //对action的名称进行排序，如果有多个，就可以看见效果了
    option.OrderActionsBy(o => o.RelativePath);
});

效果展示

前提：在Controller对应的接口上写注释