FastEndpoints项目中的OpenAPI查询参数命名策略配置指南

在FastEndpoints 6.0.0版本升级后，开发者可能会遇到OpenAPI文档中查询参数命名策略不生效的问题。本文将深入分析该问题的成因，并提供完整的解决方案。

问题现象

当使用FastEndpoints框架时，开发者配置了JSON序列化的驼峰命名策略（camelCase），但发现：

1. 响应体属性正确显示为驼峰式
2. 查询字符串参数却保持帕斯卡命名（PascalCase）

这种不一致性会影响自动生成的客户端代码，特别是在使用Kiota等工具时，由于JSON的严格大小写敏感性可能导致兼容性问题。

根本原因

经过技术分析，发现问题源于中间件管道的执行顺序。当UseFastEndpoints()中间件注册在UseSwaggerGen()或UseOpenApi()之后时，框架无法正确应用命名策略配置。

解决方案

正确配置顺序

确保中间件按以下顺序注册：

app.UseFastEndpoints(config => 
{
    config.Serializer.Options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
})
.UseSwaggerGen();  // 或.UseOpenApi().UseReDoc()

配置详解

1. 全局序列化设置：

app.UseFastEndpoints(c => 
{
    c.Serializer.Options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
});

这会统一设置请求/响应的序列化行为

2. Swagger专用设置（可选）：

services.SwaggerDocument(sd => 
{
    sd.UsePropertyNamingPolicy = true; // 默认即为true
});

技术原理

FastEndpoints的命名策略应用机制遵循以下规则：

• 中间件注册顺序决定了配置的生效时机
• UsePropertyNamingPolicy标志控制是否继承全局命名策略
• 查询参数的特殊处理发生在路由解析阶段

最佳实践建议

1. 始终将UseFastEndpoints()置于Swagger相关中间件之前
2. 对于需要特殊命名规则的场景，可使用[BindFrom]属性：

public class Request
{
    [BindFrom("customName")]
    public string StandardName { get; set; }
}

3. 测试时验证OpenAPI文档和实际请求/响应的一致性

版本兼容性说明

该行为在FastEndpoints 6.x版本中保持稳定，开发者应注意：

• .NET 9+环境下需要显式配置序列化选项
• 旧版本迁移时需检查中间件顺序
• 响应体和查询参数采用统一配置策略

通过正确理解框架的配置机制，开发者可以轻松实现全栈一致的命名策略，确保API文档与实现行为的完美同步。