Swashbuckle/NSwag动态请求体文档：JObject端点多模型记录方案咨询

云原生阿岚

2026-5-13

针对动态JObject请求体的Swagger文档方案

嘿，我来分享几个实用的方案，帮你在不拆分端点或写长篇大论注释的情况下，把不同请求模型清晰地展示在Swashbuckle/NSwag文档里：

自定义操作过滤器（最灵活的方案）
不管用Swashbuckle还是NSwag，都可以通过自定义过滤器手动为这个POST端点添加多个请求模型的Schema。以Swashbuckle为例，你可以创建一个实现IOperationFilter的类，在Apply方法里定位到目标端点，然后为请求体添加多个Schema，甚至用oneOf标记这些模型是可选的请求结构。示例代码如下：

public class DynamicRequestBodyFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 匹配你的目标端点，这里可以根据路由、动作名等判断
        if (context.ApiDescription.HttpMethod == HttpMethod.Post.Method && 
            context.ApiDescription.ActionDescriptor.RouteValues["action"] == "Post")
        {
            // 生成两个请求模型的Schema
            var schemaA = context.SchemaGenerator.GenerateSchema(typeof(RequestModelA), context.SchemaRepository);
            var schemaB = context.SchemaGenerator.GenerateSchema(typeof(RequestModelB), context.SchemaRepository);
            
            // 更新请求体的Schema，用oneOf表示支持多种结构
            operation.RequestBody.Content["application/json"].Schema = new OpenApiSchema
            {
                OneOf = new List<OpenApiSchema> { schemaA, schemaB },
                Description = "此端点支持以下两种请求结构："
            };
        }
    }
}

然后在Startup/Program.cs里注册这个过滤器：

services.AddSwaggerGen(c =>
{
    c.OperationFilter<DynamicRequestBodyFilter>();
});

NSwag的思路类似，你可以实现IOpenApiOperationProcessor来修改操作的请求体配置。

请求示例属性+过滤器结合
Swashbuckle提供了[SwaggerRequestExample]属性，NSwag也有类似机制，你可以给JObject参数标记多个示例模型，再配合过滤器把这些示例对应的Schema自动添加到文档中。比如：
```
public Task<SomeResponse> Post(
    [SwaggerRequestExample(typeof(RequestModelA), typeof(RequestModelAExample))]
    [SwaggerRequestExample(typeof(RequestModelB), typeof(RequestModelBExample))]
    JObject request)
{
    // 方法逻辑实现
}
```
你需要编写对应的示例类（比如RequestModelAExample返回一个实例），然后用过滤器读取这些属性关联的模型类型，生成并合并Schema。这种方式更贴合属性驱动的开发习惯，代码侵入性更低。

XML注释补充结构化示例
如果你不想写太多代码，可以在XML注释里用<remarks>标签详细列出不同请求模型的JSON示例。虽然这不是自动生成的Schema，但能让调用者直观看到可能的请求结构，足够作为文档说明。示例如下：

/// <summary>
/// 处理动态请求的POST端点
/// </summary>
/// <param name="request">动态请求体，支持以下两种结构</param>
/// <remarks>
/// 示例1（RequestModelA结构）：
/// <code>
/// {
///   "propertyA": "示例值",
///   "numericField": 123
/// }
/// </code>
/// 示例2（RequestModelB结构）：
/// <code>
/// {
///   "propertyB": true,
///   "listField": ["条目1", "条目2"]
/// }
/// </code>
/// </remarks>
public Task<SomeResponse> Post(JObject request) { ... }

记得在项目设置里启用XML文档生成，Swashbuckle/NSwag会自动读取这些注释。

强类型基类+动态解析
你可以定义一个基类或接口，让所有可能的请求模型都继承它，然后把端点参数换成这个基类，配合JSON转换器在方法内部自动解析成具体类型。比如：

public abstract class BaseRequest { }
public class RequestModelA : BaseRequest 
{ 
    public string PropertyA { get; set; } 
    public int NumericField { get; set; }
}
public class RequestModelB : BaseRequest 
{ 
    public bool PropertyB { get; set; } 
    public List<string> ListField { get; set; }
}

public Task<SomeResponse> Post([FromBody] BaseRequest request)
{
    // 根据具体类型处理逻辑
    if (request is RequestModelA modelA)
    {
        // 处理ModelA的逻辑
    }
    else if (request is RequestModelB modelB)
    {
        // 处理ModelB的逻辑
    }
    // ...
}

Swashbuckle/NSwag会自动识别基类的所有派生类型，生成包含oneOf的Schema，文档里会清晰展示所有可能的请求结构。这个方案需要调整现有参数类型，但文档生成更自动化，不需要额外写过滤器。

内容的提问来源于stack exchange，提问作者Andrei