FastEndpoints项目中的Swagger显示与JSON序列化问题解析

问题背景

在使用FastEndpoints框架开发Web API时，开发者可能会遇到两个常见问题：Swagger UI显示异常和JSON响应中出现额外字段。这些问题虽然不影响功能实现，但会影响API文档的可读性和响应数据的整洁性。

Swagger UI显示异常问题

现象描述

当使用FluentValidation验证器对Email字段进行格式验证时，Swagger UI界面会显示乱码字符，而不是正常的示例值。这种情况特别容易出现在使用.EmailAddress()验证规则的字段上。

问题根源

经过分析，这是Swagger UI自身的一个显示bug。当验证规则中包含"pattern"字段时（Email验证会自动添加正则表达式模式），Swagger UI的渲染引擎会出现异常。实际上，生成的swagger.json文件内容是正确的，只是UI显示层出现了问题。

解决方案

有两种方法可以解决这个问题：

1. 使用DefaultValue特性：为属性添加默认值示例

[DefaultValue("[e-mail]")]
public string Email { get; set; }

2. 使用XML注释示例：通过文档注释提供示例值

/// <example>
/// [e-mail]
/// </example>
public string Email { get; set; }

这两种方法都能强制Swagger UI显示正确的示例值，避免乱码问题。

JSON序列化额外字段问题

现象描述

API响应中出现了非预期的额外字段，如$id和$values。例如：

{
  "$id": "1",
  "id": 1,
  "email": "[e-mail]",
  "token": "eyJhbGciOiJodHRw..."
}

对于集合类型响应，还会出现$values字段包装实际数据。

问题根源

这个问题源于项目配置中设置了特殊的JSON序列化选项：

c.Serializer.Options.ReferenceHandler = ReferenceHandler.Preserve;

ReferenceHandler.Preserve是System.Text.Json提供的一个功能，用于处理对象图中的循环引用。它会为每个对象添加$id标识符，并在引用相同对象时使用$ref指向该标识符，从而避免无限循环。

解决方案

如果API响应中不需要处理复杂的对象图循环引用，最简单的解决方案是移除这行配置，让序列化器使用默认行为：

c.Serializer.Options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
// 移除 ReferenceHandler.Preserve 设置

这样生成的JSON响应将保持简洁，不包含额外的元数据字段。

最佳实践建议

1. Swagger文档优化：为重要字段添加XML注释和示例值，不仅能解决显示问题，还能提升API文档质量。

2. JSON序列化配置：除非确实需要处理复杂对象图的循环引用，否则应避免使用ReferenceHandler.Preserve。大多数Web API场景下，简单的DTO结构不需要这种高级功能。

3. 响应设计原则：保持API响应的简洁性和一致性，避免暴露不必要的技术细节给客户端。

通过理解这些问题背后的原理并应用适当的解决方案，开发者可以构建出更加专业和易用的Web API服务。