NSwag生成Swagger时string[]类型请求头序列化异常问题咨询

问题根源 #

根据OpenAPI 3.0规范，请求头中的数组类型参数必须使用simple风格（即逗号分隔的单一值，如permissions: 1,2,3），但NSwag默认会对[FromHeader]标记的数组参数生成style: form且explode: true的配置。这种配置会让客户端生成重复的请求头键（如permissions=1&permissions=2&permissions=3），而HTTP请求头的解析逻辑会将这类格式合并为单个字符串"1&permissions=2&permissions=3"，导致控制器接收到的数组不符合预期。

修复方案 #

这是NSwag的默认配置问题，而非Bug，可通过以下两种方式修复：

1. 全局配置修正

在NSwag的文档生成配置中，全局强制将请求头类型的数组参数设为simple风格。如果是在.NET 8的Program.cs中配置OpenAPI文档，可添加自定义处理器：

services.AddOpenApiDocument(settings =>
{
    settings.OperationProcessors.Add(new OperationProcessor(context =>
    {
        foreach (var param in context.OperationDescription.Operation.Parameters)
        {
            // 匹配所有请求头位置的数组参数
            if (param.Location == OpenApiParameterLocation.Header 
                && param.Schema.Type == JsonObjectType.Array)
            {
                param.Style = OpenApiParameterStyle.Simple;
                param.Explode = false;
            }
        }
        return true;
    }));
});

2. 单个参数特性标记

通过NSwag.Annotations包提供的特性，单独指定该参数的风格。首先安装NuGet包NSwag.Annotations，然后修改控制器参数：

[FromHeader]
[OpenApiParameter(Style = OpenApiParameterStyle.Simple, Explode = false)]
IEnumerable<string> permissions

验证 #

修改配置后重新生成OpenAPI文档，检查permissions参数的定义：

{
  "name": "permissions",
  "in": "header",
  "style": "simple",
  "explode": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

此时客户端会以permissions: 1,2,3的格式发送请求，控制器就能正确接收到数组["1", "2", "3"]。

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