.NET Framework WebAPI MVC如何让Swagger UI显示多版本接口

你已经正确标记了API版本，但Swagger没识别到1.1版本的接口，核心原因是API版本控制和Swagger的集成配置缺失。下面是一步步的解决方案：

1. 安装必要的NuGet包 #

先确保项目安装了以下核心包（通过NuGet包管理器或Package Manager Console）：

• Microsoft.AspNet.WebApi.Versioning：API版本控制核心组件
• Microsoft.AspNet.WebApi.Versioning.ApiExplorer：让Swagger能识别API版本的元数据探索器
• Swashbuckle.AspNetWebApi（或旧版Swashbuckle）：Swagger文档生成工具

2. 更新WebApiConfig配置 #

修改WebApiConfig.Register方法，添加版本化API探索器的配置，让Swagger能获取所有版本的接口元数据：

public static class WebApiConfig {
    public static void Register(HttpConfiguration config) {
        // 1. 配置API版本控制核心选项
        config.AddApiVersioning(options => {
            options.ReportApiVersions = true; // 响应头返回支持的API版本
            options.AssumeDefaultVersionWhenUnspecified = true;
            options.DefaultApiVersion = new ApiVersion(1, 0);
        });

        // 2. 添加版本化API探索器，为Swagger提供版本分组支持
        var apiExplorer = config.AddVersionedApiExplorer(options => {
            options.GroupNameFormat = "'v'V"; // 分组格式为v1.0、v1.1
            options.SubstituteApiVersionInUrl = true;
        });

        // 3. 保留原有路由配置，确保版本约束生效
        var constraintResolver = new DefaultInlineConstraintResolver {
            ConstraintMap = { ["apiVersion"] = typeof(ApiVersionRouteConstraint) }
        };
        config.MapHttpAttributeRoutes(constraintResolver);

        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}"
        );
    }
}

3. 配置Swagger生成器（SwaggerConfig.cs） #

如果项目没有SwaggerConfig.cs，安装Swashbuckle后会自动生成，修改它为每个API版本创建独立的Swagger文档：

public class SwaggerConfig {
    public static void Register() {
        var config = GlobalConfiguration.Configuration;
        // 获取版本化的API探索器实例
        var apiExplorer = config.GetApiExplorer() as IApiVersionDescriptionProvider;

        // 为每个API版本生成Swagger文档
        foreach (var versionDesc in apiExplorer.ApiVersionDescriptions) {
            config.EnableSwagger(
                $"v{versionDesc.ApiVersion}", // 文档唯一标识
                swaggerConfig => {
                    swaggerConfig.SwaggerDoc(
                        $"v{versionDesc.ApiVersion}", 
                        new Info {
                            Title = $"Foo API {versionDesc.ApiVersion}",
                            Version = versionDesc.ApiVersion.ToString(),
                            Description = versionDesc.IsDeprecated ? "⚠️ 此版本已废弃" : "✅ 当前版本"
                        }
                    );

                    // 让Swagger识别Obsolete标记，废弃接口显示划掉样式
                    swaggerConfig.OperationFilter<ObsoleteOperationFilter>();

                    // 可选：添加XML注释，显示接口参数/返回值详情
                    // swaggerConfig.IncludeXmlComments($"{AppDomain.CurrentDomain.BaseDirectory}\\bin\\YourApiAssembly.xml");
                }
            );
        }

        // 配置Swagger UI，允许切换不同版本的API文档
        config.EnableSwaggerUi(uiConfig => {
            foreach (var versionDesc in apiExplorer.ApiVersionDescriptions) {
                uiConfig.SwaggerEndpoint(
                    $"/swagger/v{versionDesc.ApiVersion}/swagger.json", 
                    $"API Version {versionDesc.ApiVersion}"
                );
            }
        });
    }
}

4. 可选：优化控制器接口命名 #

你的1.1版本接口命名为FooInfo2，其实可以改成FooInfo——只要路由和ApiVersion属性不同，WebAPI允许同名方法（路由不同即可区分），这样代码更整洁：

public class FooController : BaseFundApiController<FooRequest> {
    [Obsolete]
    [ApiVersion("1.0")]
    [Route("api/v1.0/Foo")]
    [ResponseType(typeof(FooResponse))]
    public async Task<HttpResponseMessage> FooInfo([FromBody] FooRequest FooRequest) { }

    [ApiVersion("1.1")]
    [Route("api/v1.1/Foo")]
    [ResponseType(typeof(FooResponse))]
    public async Task<HttpResponseMessage> FooInfo([FromBody] FooRequest FooRequest) { }
}

为什么之前只显示1.0版本？ #

你之前只调用了config.AddApiVersioning()，但没有配置AddVersionedApiExplorer()——这个组件负责把不同版本的API元数据暴露给Swagger。没有它，Swagger只能识别到带有Obsolete标记的1.0接口，而无法发现1.1版本的接口。

完成以上配置后，启动项目打开Swagger UI，就能看到版本选择下拉框，同时显示v1.0（划掉的废弃版本）和v1.1（当前版本）的接口了。

内容的提问来源于stack exchange，提问作者Rob Sedgwick