C# Web API集成Scalar参数不显示问题排查求助

我在C# Web API项目中集成Scalar时遇到参数无法显示的问题。我的接口方法签名如下：

public async Task<IActionResult> SendFile(IFormFile uploadedFile, [FromForm] string? password)

按照微软官方文档，内置OpenAPI支持应该基于[FromForm]属性生成表单参数，Swagger能正常显示这些参数，但Scalar却把请求体识别为JSON，不符合预期。对比两者生成的OpenAPI JSON，发现内置OpenAPI生成的文档中包含allOf结构，而Swagger生成的没有，想确认allOf是否是问题根源，以及如何在不使用hack式转换器的前提下解决。

问题根源确认 #

是的，allOf结构就是导致Scalar解析异常的原因。Swagger的解析逻辑能正确处理表单参数场景下的allOf扩展，但Scalar的OpenAPI解析器会将这种结构误判为JSON请求体，从而无法正确渲染表单参数。

解决方案 #

方案1：禁用OpenAPI生成器的allOf扩展 #

通过配置内置OpenAPI生成器的选项，直接避免生成allOf结构：

builder.Services.AddOpenApi(options =>
{
    options.GeneratorOptions.SchemaGeneratorOptions.UseAllOfForInheritance = false;
    options.GeneratorOptions.SchemaGeneratorOptions.UseAllOfToExtendReferenceSchemas = false;
});

这个配置会让OpenAPI生成器直接生成扁平化的参数结构，而非通过allOf扩展，Scalar就能正确识别表单参数了。

方案2：自定义OperationFilter修正表单参数定义 #

如果方案1无法解决（比如需要保留继承场景下的allOf），可以通过自定义IOperationFilter来手动修正表单参数的OpenAPI定义：

1. 创建过滤器类：

using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using Microsoft.AspNetCore.OpenApi;
using System.Reflection;

public class FormParameterFixFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 筛选出带[FromForm]标记的参数和IFormFile参数
        var formParams = context.MethodInfo.GetParameters()
            .Where(p => p.GetCustomAttribute<FromFormAttribute>() != null || p.ParameterType == typeof(IFormFile))
            .ToList();

        if (!formParams.Any()) return;

        // 清除自动生成的错误请求体
        operation.RequestBody = null;
        operation.Parameters.RemoveAll(p => p.In == ParameterLocation.FormData);

        // 构建multipart/form-data类型的请求体
        var formSchema = new OpenApiSchema { Type = "object", Properties = new Dictionary<string, OpenApiSchema>() };
        var requiredFields = new HashSet<string>();

        foreach (var param in formParams)
        {
            var schema = context.SchemaGenerator.GenerateSchema(param.ParameterType, context.SchemaRepository);
            // 处理IFormFile的特殊格式
            if (param.ParameterType == typeof(IFormFile))
            {
                schema.Type = "string";
                schema.Format = "binary";
            }

            formSchema.Properties[param.Name] = schema;
            if (!param.IsOptional)
            {
                requiredFields.Add(param.Name);
            }
        }

        formSchema.Required = requiredFields;

        operation.RequestBody = new OpenApiRequestBody
        {
            Content = new Dictionary<string, OpenApiMediaType>
            {
                ["multipart/form-data"] = new OpenApiMediaType { Schema = formSchema }
            }
        };
    }
}

2. 注册过滤器：

builder.Services.AddOpenApi(options =>
{
    options.GeneratorOptions.OperationFilters.Add(new FormParameterFixFilter());
});

这个过滤器会手动构建符合multipart/form-data规范的请求体定义，替换掉自动生成的包含allOf的结构，确保Scalar能正确识别并渲染表单参数。

验证 #

修改配置后，重新启动项目，查看生成的OpenAPI文档，确认allOf结构已被移除或替换，此时Scalar应该能正常显示uploadedFile和password表单参数。

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