Swashbuckle.AspNetCore 中 FromQuery 参数与枚举类型的正确使用

问题背景

在使用 Swashbuckle.AspNetCore 生成 OpenAPI/Swagger 文档时，开发人员可能会遇到一个关于枚举类型参数的特殊情况。当控制器方法使用 [FromQuery] 属性标记参数，并且该参数包含枚举类型时，生成的 OpenAPI 文档可能不会按照预期方式处理枚举定义。

典型场景分析

考虑以下控制器代码示例：

[ApiController]
[Route("api/[controller]")]
public class MyController : ControllerBase
{
    [HttpGet("MyGet")]
    public Task<ActionResult<GetResponse>> Get([FromQuery] GetRequest request, CancellationToken cancellationToken)
    {
        return Task.FromResult<ActionResult<GetResponse>>(Ok(new GetResponse([])));
    }
}

public record GetRequest(string Version, IEnumerable<ClientType> ClientTypes);
public enum ClientType { Agent, Client }

开发人员期望生成的 OpenAPI 文档中，ClientType 枚举应该被定义在 components/schemas 部分，并通过 $ref 引用。然而实际生成的文档可能直接将枚举值内联在参数定义中，导致下游工具（如 Refitter）无法正确识别枚举类型。

根本原因

这个问题通常与 Swashbuckle 的配置有关。特别是当使用了 UseInlineDefinitionsForEnums() 方法时，它会强制 Swashbuckle 将枚举定义内联而不是作为独立的 schema 组件。

services.AddSwaggerGen(c => {
    c.UseInlineDefinitionsForEnums(); // 这会导致枚举被内联处理
});

解决方案

要解决这个问题，可以采取以下步骤：

1. 移除内联枚举配置：检查并移除 UseInlineDefinitionsForEnums() 调用

2. 确保正确的 JSON 序列化设置：在 Startup 或 Program 类中配置 JSON 选项以支持枚举的字符串表示

builder.Services.AddControllers()
    .AddJsonOptions(options => {
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
    });

3. 验证生成的 OpenAPI 文档：确保枚举类型现在正确地出现在 components/schemas 部分

最佳实践

1. 保持一致性：对于 API 中的枚举类型，建议统一采用字符串表示形式，这能提高 API 的互操作性

2. 文档清晰：确保生成的 OpenAPI 文档中枚举类型有明确的定义和描述

3. 测试工具链：在使用 Swashbuckle 生成文档后，应该用下游工具（如客户端生成器）验证生成的文档是否被正确解析

总结

Swashbuckle.AspNetCore 在处理 [FromQuery] 参数中的枚举类型时，其行为可以通过配置进行精细控制。理解 UseInlineDefinitionsForEnums() 方法的影响是关键。通过适当的配置，可以确保生成的 OpenAPI 文档既符合规范又能被下游工具正确解析。

对于需要从查询参数传递枚举值的 API 设计，这种配置尤为重要，因为它直接影响到 API 文档的质量和可用性。