FastEndpoints中自定义Swagger文档参数类型的技巧

在FastEndpoints项目中，开发者经常需要处理API文档生成的问题。本文将深入探讨如何通过自定义操作处理器来优化Swagger文档中的参数类型定义，特别是如何将简单的字符串参数转换为枚举类型显示。

问题背景

在API开发中，我们通常会定义查询参数类来绑定请求参数。例如：

public class Query
{
    public ConnectionKind? Kind { get; set; }
    public string? Type { get; set; }
}

其中ConnectionKind是一个枚举类型，而Type是一个字符串类型。默认情况下，Swagger文档会正确地将枚举类型显示为可选值列表，但对于字符串类型，即使它实际上只接受特定值，也会简单地显示为文本输入。

解决方案

FastEndpoints提供了强大的扩展能力，我们可以通过实现IOperationProcessor接口来自定义Swagger文档的生成逻辑。

自定义操作处理器实现

首先，我们定义一个标记接口来标识需要特殊处理的参数类：

public interface IHasQueryType
{
    string Type { get; set; }
}

然后让查询参数类实现这个接口：

public class Query : IHasQueryType
{
    public string Type { get; set; }
}

接下来是实现核心逻辑的自定义操作处理器：

public class QueryTypeOperationProcessor : IOperationProcessor
{
    public bool Process(OperationProcessorContext ctx)
    {
        // 检查端点是否实现了我们的标记接口
        if (ctx.GetEndpointDefinition()?.ReqDtoType.GetInterfaces()
            .Contains(typeof(IHasQueryType)) != true)
            return true;

        // 遍历所有查询参数
        foreach (var param in ctx.OperationDescription.Operation.Parameters
            .Where(p => p.Kind == OpenApiParameterKind.Query))
        {
            if (!param.Name.Equals(nameof(IHasQueryType.Type), 
                StringComparison.OrdinalIgnoreCase))
                continue;

            // 添加枚举值
            param.Schema.Enumeration.Add("CONTENTFUL");
            param.Schema.Enumeration.Add("KENTICO");
            param.Schema.Enumeration.Add("NOTION");
            
            // 添加友好的显示名称
            param.Schema.ExtensionData ??= new Dictionary<string, object?>();
            param.Schema.ExtensionData["x-enumNames"] = new[] { 
                "Contentful", "Kentico", "Notion" };
        }

        return true;
    }
}

注册处理器

最后，在应用程序启动时注册这个处理器：

builder.Services.SwaggerDocument(o => 
    o.DocumentSettings = s => s.OperationProcessors.Add(new QueryTypeOperationProcessor()));

实现效果

通过这种方式，原本在Swagger文档中显示为普通字符串输入的Type参数，现在会显示为下拉选择框，包含我们指定的可选值和对应的友好名称。这不仅提升了API文档的可读性，也为API使用者提供了更明确的参数输入指导。

最佳实践

1. 保持一致性：确保文档中的枚举值与实际API处理逻辑一致
2. 提供完整选项：列出所有可能的有效值
3. 使用友好名称：x-enumNames可以提供更易读的显示名称
4. 考虑国际化：如果需要支持多语言，可以扩展处理器逻辑

这种技术不仅适用于查询参数，也可以应用于路由参数、请求体等任何需要特殊文档处理的场景，为FastEndpoints项目提供更灵活的API文档定制能力。