FastEndpoints中JsonElement在Swagger文档中的显示问题解析

在FastEndpoints框架中，开发人员可能会遇到一个常见问题：当API响应或请求模型中包含JsonElement类型属性时，Swagger文档无法正确显示该属性的示例值。本文将深入分析该问题的成因，并提供解决方案。

问题现象

当开发者在FastEndpoints中定义如下响应模型时：

public sealed record GetEventResponse
{
    public required int OperationId { get; init; }
    public required string Name { get; init; }
    public required DateTime HappenedAt { get; init; }
    public required JsonElement? AdditionalInformation { get; init; }
}

并在端点配置中设置示例响应：

Response(200, "ok response with body", example: new GetEventResponse
{
    OperationId = 123456,
    Name = "OrderCreated",
    HappenedAt = DateTime.Now,
    AdditionalInformation = JsonDocument.Parse(JsonSerializer.Serialize(new {User = "Terry"})).RootElement
});

Swagger文档会显示如下不完整的信息：

{
  "operationId": 123456,
  "name": "OrderCreated",
  "happenedAt": "2024-02-15T08:56:31.1856026+01:00",
  "additionalInformation": {}
}

问题根源

该问题的根本原因在于Swagger文档生成工具NSwag内部使用的是Newtonsoft.Json库，而JsonElement类型属于System.Text.Json命名空间。这两个不同的JSON处理库之间存在兼容性问题：

1. NSwag无法正确识别System.Text.Json.JsonElement类型的结构
2. 在序列化过程中，JsonElement的内部数据结构无法被Newtonsoft.Json完整解析
3. 导致最终生成的Swagger文档中，JsonElement属性只能显示为空对象

解决方案

针对这个问题，推荐使用更通用的object类型替代JsonElement：

public sealed record GetEventResponse
{
    public required int OperationId { get; init; }
    public required string Name { get; init; }
    public required DateTime HappenedAt { get; init; }
    public required object? AdditionalInformation { get; init; }
}

然后在示例中直接使用匿名对象：

Response(200, "ok response with body", example: new GetEventResponse
{
    OperationId = 123456,
    Name = "OrderCreated",
    HappenedAt = DateTime.Now,
    AdditionalInformation = new { User = "Terry" }
});

方案优势

1. 兼容性更好：object类型能被所有JSON序列化库正确处理
2. 代码更简洁：无需额外的JsonDocument.Parse和JsonSerializer.Serialize调用
3. 可读性更高：直接在代码中看到数据结构，而不是通过序列化字符串
4. 维护更方便：类型变更时不需要修改序列化逻辑

实际应用建议

在实际开发中，如果API需要处理动态JSON数据，可以考虑以下最佳实践：

1. 对于简单的动态数据，使用object类型
2. 对于复杂结构，考虑定义明确的DTO类
3. 如果确实需要JsonElement的功能，可以在内部处理时进行类型转换
4. 在Swagger文档中，优先使用具体类型或object而非JsonElement

通过这种方式，可以确保Swagger文档正确显示API的结构，同时保持代码的灵活性和可维护性。