如何在Swagger文档中将Route特性的{version}占位符替换为实际版本值

要实现SwaggerUI中路由版本占位符替换为实际版本号，需要通过**自定义IOperationFilter**修改接口路径，同时确保多版本Swagger文档配置正确，具体步骤如下：

1. 配置API版本管理（若未配置） #

首先确保项目启用API版本功能，在Program.cs中添加：

builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
});

builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV"; // 定义版本显示格式为v1、v2
    options.SubstituteApiVersionInUrl = true;
});

2. 实现自定义IOperationFilter #

创建过滤器类，替换路径中的{version}占位符为当前Swagger文档的实际版本号：

public class ReplaceVersionInPathFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 获取当前Swagger文档对应的版本号
        var currentVersion = context.ApiDescription.SwaggerDoc.Version;
        
        // 替换路径中的{version}占位符
        operation.Path = operation.Path.Replace("{version}", currentVersion);
    }
}

3. 注册过滤器并配置多版本Swagger文档 #

在Program.cs的Swagger配置中注册过滤器，并添加不同版本的文档：

builder.Services.AddSwaggerGen(c =>
{
    // 注册v1版本文档
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    // 注册v2版本文档
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });

    // 将自定义过滤器添加到Swagger生成流程
    c.OperationFilter<ReplaceVersionInPathFilter>();
});

4. 配置SwaggerUI中间件 #

在中间件管道中启用SwaggerUI，并指定各版本文档的端点：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
});

说明 #

• 之前尝试的ISchemaFilter用于修改API模型的Schema定义，不负责接口路径处理，因此无法实现需求。
• IOperationFilter可访问每个接口的OpenApiOperation对象，其中包含接口路径信息，通过替换占位符即可实现版本号的真实显示。

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