.NET 4.8 MVC中Swashbuckle生成Swagger文档时非id命名参数的接口无法生成文档的问题

嗨，你猜的完全没错！这个问题的根源确实是路由模板的占位符和接口参数名称不匹配导致的。我来给你拆解一下原因，再给几个不改动现有路由和接口行为的解决方案：

问题原因 #

Swashbuckle在生成Swagger文档时，会自动关联接口参数和路由模板里的占位符：

• 对于Post和Post3，参数名是id，正好匹配你默认路由里的{id}占位符，所以Swashbuckle能正确识别这是路由参数，顺利生成文档。
• 而Post2的参数是ids，你的路由模板里没有对应的{ids}占位符，Swashbuckle没法确定这个参数是通过路由传递还是查询字符串传递，干脆就跳过了这个接口的文档生成。

解决方案（完全不影响现有生产代码行为） #

方案1：给参数标记[FromQuery]（适合参数作为查询字符串传递的场景）

如果Post2的ids是通过查询字符串传递的（比如请求地址是/Fake/Post2?ids=123），只需要给参数加个[FromQuery]特性，明确告诉Swashbuckle这是查询参数：

/// <summary>
/// Post2 
/// </summary>
/// <param name="ids"></param>
/// <returns></returns>
// GET: api/items/post2/{ids}
public int Post2([FromQuery] int ids)
{
    return 0;
}

这样改动后，Swashbuckle就能识别到这个参数并生成文档，同时完全不影响现有接口的调用方式。

方案2：给方法添加[Route]特性（适合参数作为路由参数传递的场景）

如果Post2的ids是通过路由传递的（比如请求地址是/Fake/123/Post2），给方法加个显式的路由属性，匹配现有路由行为的同时让Swashbuckle识别参数：

/// <summary>
/// Post2 
/// </summary>
/// <param name="ids"></param>
/// <returns></returns>
// GET: api/items/post2/{ids}
[Route("{ids}/Post2")]
public int Post2(int ids)
{
    return 0;
}

这个路由属性会和你的默认路由兼容，既保留原有访问方式，又让Swashbuckle能关联ids参数和路由占位符，顺利生成文档。

方案3：全局配置Swashbuckle参数解析（适合多个类似接口的场景）

如果你有很多类似的接口需要处理，可以自定义Swashbuckle的操作过滤器，批量识别非id命名的路由参数：
在Swashbuckle的配置代码里添加：

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "你的API名称");
    // 注册自定义过滤器
    c.OperationFilter<CustomRouteParameterFilter>();
});

// 自定义操作过滤器
public class CustomRouteParameterFilter : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        foreach (var paramDesc in apiDescription.ParameterDescriptions)
        {
            // 识别路由来源的参数
            if (paramDesc.Source == ApiParameterSource.FromUri && paramDesc.RouteInfo != null)
            {
                // 如果Swagger里还没这个参数，手动添加
                var existingParam = operation.parameters?.FirstOrDefault(p => p.name == paramDesc.Name);
                if (existingParam == null)
                {
                    operation.parameters.Add(new Parameter
                    {
                        name = paramDesc.Name,
                        @in = "path",
                        required = !paramDesc.RouteInfo.IsOptional,
                        type = schemaRegistry.GetOrRegister(paramDesc.ParameterDescriptor.ParameterType).type
                    });
                }
            }
        }
    }
}

这个过滤器会主动扫描所有路由参数，不管名称是什么，都添加到Swagger文档里，适合批量处理的场景。

验证 #

不管用哪种方案，修改后重启项目，Swagger就能正常生成Post2的文档了，而且完全不会影响现有生产环境的接口调用。

备注：内容来源于stack exchange，提问作者Hockeymtl