Swashbuckle 5.6.0为何在GET参数中包含变量名？

在旧.NET Framework项目中使用Swashbuckle 5.6.0时，将POCO类作为GET请求的参数会出现异常行为：所有参数被自动加上了类参数的变量名前缀（比如示例中的record.），导致调用API时必须在每个参数前拼接该前缀，操作繁琐。

相关信息说明 #

• Swagger界面显示：所有请求参数均带有record.前缀，如record.Id、record.FromCreated等
• 控制器定义：GET接口接收AssetTransactionAllAssetsSearchRecord2类型的参数record

POCO类代码 #

public class AssetTransactionAllAssetsSearchRecord2
{
    public AssetTransactionAllAssetsSearchRecord2() { }
    
    public long Id { get; set; }
    public DateTime FromCreated { get; set; }
    public DateTime ToCreated { get; set; }
    public long? DocumentId { get; set; }

    public long AssetId { get; set; }
    public long HostingAssetId { get; set; }
    public long SystemAssetId { get; set; }
    public long CustomerAssetId { get; set; }

    public string AssetCode { get; set; }
    public string HostingAssetCode { get; set; }
    public string SystemAssetCode { get; set; }
    public string CustomerAssetCode { get; set; }

    public string AssetName { get; set; }
    public string HostingAssetName { get; set; }
    public string SystemAssetName { get; set; }
    public string CustomerAssetName { get; set; }
}

Swagger配置代码 #

using System.Web.Http;
using WebActivatorEx;
using VI_Web;
using Swashbuckle.Application;
using Swashbuckle.Swagger;
using System.Collections.Generic;
using System.Web.Http.Description;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace VI_Web
{
    class AuthTokenOperation : IDocumentFilter
    {
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        {
            swaggerDoc.paths.Add("/token", new PathItem
            {
                post = new Operation
                {
                    tags = new List<string> { "UserAuth" },
                    consumes = new List<string>
                    {
                        "application/x-www-form-urlencoded"
                    },
                    parameters = new List<Parameter> {
                        new Parameter
                        {
                            type = "string",
                            name = "grant_type",
                            required = true,
                            @in = "formData",
                            @default = "password"
                        },
                        new Parameter
                        {
                            type = "string",
                            name = "client_id",
                            required = true,
                            @in = "formData"
                        },
                        new Parameter
                        {
                            type = "string",
                            name = "client_secret",
                            required = true,
                            @in = "formData"
                        },
                        new Parameter
                        {
                            type = "string",
                            name = "database",
                            required = true,
                            @in = "formData"
                        }
                    }
                }
            });
        }
    }

    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                {
                    c.SingleApiVersion("v1", "VI_Web");
                    c.ApiKey("Token")
                      .Description("Filling bearer token here")
                      .Name("Authorization")
                      .In("header");
                    c.DocumentFilter<AuthTokenOperation>();
                })
                .EnableSwaggerUi(c =>
                {
                    c.EnableApiKeySupport("Authorization", "header");
                });
        }
    }
}

原因解释 #

1. Web API模型绑定规则限制：.NET Framework的Web API处理GET请求的复杂类型参数时，由于GET请求没有请求体，所有参数只能通过URL查询字符串传递。为了区分不同复杂类型参数的属性、避免命名冲突，框架默认采用参数名称前缀的方式绑定属性值，即通过变量名.属性名的格式来识别对应属性。
2. Swashbuckle 5.6.0的默认行为：该版本的Swashbuckle严格遵循Web API的模型绑定逻辑，生成Swagger文档时会直接沿用这种带前缀的参数格式，不会自动扁平化复杂类型参数。因此Swagger界面上会显示record.XXX这类参数名。
3. 未配置扁平化绑定：如果没有给控制器参数添加[FromUri]特性并启用扁平化绑定，Web API和Swashbuckle都会默认使用带前缀的参数格式。

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