Swashbuckle.AspNetCore 中 Minimal API 的 FromForm 参数 OpenAPI 规范生成问题解析

问题背景

在 ASP.NET Core 的 Minimal API 开发中，开发者发现了一个关于 OpenAPI 规范生成的异常行为。当使用 [FromForm] 参数时，是否调用 WithOpenApi() 扩展方法会导致生成的 OpenAPI 规范（swagger.json）出现显著差异。

问题现象

开发者定义了两个几乎相同的端点：

app.MapPost("/api/products", ([FromForm] Product product) => { ... })
    .DisableAntiforgery();

app.MapPost("/api/products-with-openapi", ([FromForm] Product product) => { ... })
    .DisableAntiforgery()
    .WithOpenApi();

虽然这两个端点功能相同，但生成的 OpenAPI 规范却大不相同：

1. 未使用 WithOpenApi() 的端点：生成的规范将整个 Product 对象包装在一个名为 "product" 的表单字段中
2. 使用 WithOpenApi() 的端点：生成的规范直接将 Product 的属性展开为表单字段

技术分析

规范差异的本质

这种差异源于 Swashbuckle.AspNetCore 对 Minimal API 的不同处理方式：

1. 默认处理：框架将 [FromForm] 参数视为一个整体对象，认为客户端应该以单个字段的形式提交
2. WithOpenApi 处理：扩展方法触发了更精细的分析，将复杂类型的属性展开为独立的表单字段

正确性判断

从 RESTful API 设计和实际使用角度来看，WithOpenApi() 生成的规范更符合预期。通常，表单提交应该将复杂对象的属性展开为独立的表单字段，而不是将整个对象序列化为单个字段值。

底层机制

这种差异反映了 ASP.NET Core 内部对 API 描述的两种处理路径：

1. 反射式 API 描述：WithOpenApi() 强制框架通过反射分析参数类型
2. 默认推断：没有明确指示时，框架采用更保守的参数处理方式

解决方案

项目维护者已经确认这是一个需要修复的问题，并提出了以下解决路径：

1. 统一处理逻辑：使 Minimal API 无论是否使用 WithOpenApi() 都生成相同的 OpenAPI 规范
2. 属性级展开：确保复杂类型的属性被正确展开为独立的表单字段
3. 向后兼容：在修复过程中考虑现有实现的兼容性

开发者建议

在官方修复发布前，开发者可以采用以下临时解决方案：

1. 一致使用 WithOpenApi()：确保所有需要正确 OpenAPI 文档的端点都使用此扩展方法
2. 自定义文档生成：通过实现自定义的 IOperationFilter 来修正不符合预期的文档

总结

这个问题揭示了 Swashbuckle.AspNetCore 在处理 Minimal API 与 OpenAPI 集成时的一个边界情况。理解这种差异有助于开发者在设计 API 时做出更明智的选择，同时也提醒我们在依赖自动文档生成时需要进行充分的验证。

随着 .NET 生态中 Minimal API 的普及，这类工具链的整合问题将越来越受到重视，开发者可以期待未来版本中更一致和可靠的行为。