如何在.NET 9 Minimal API中用内置OpenAPI实现参数示例？

核心问题分析 #

你遇到的问题本质是：内置OpenAPI需要基于OpenAPI模型对象（而非序列化后的字符串）定义示例，同时要匹配请求体的Schema结构，才能让UI正确渲染并自动适配不同MIME类型。

解决方案 #

1. 用OpenApiObject构建示例（自动适配序列化）

无需手动针对每个ContentType做序列化，直接构建OpenApiObject实例，内置OpenAPI系统会根据选中的MIME类型自动完成序列化，同时避免示例被拆分为单个属性条目。

2. 修正示例绑定逻辑

确保将示例赋值给OpenApiMediaType.Example（单个示例场景），而非Examples集合（多示例场景用），这样UI会正确渲染完整示例结构。

改进后的代码 #

app.MapPost("/", (
    IDictionary<string, object> values, IMyService service) =>
{
    var response = service.CreateTask(values);
    return Results.Ok(response);
})
.WithSummary("Create a new record")
.RequireAuthorization("AllowTaskCreate")
.WithOpenApi(op =>
{
    // 构建匹配IDictionary结构的示例对象
    var sample = new OpenApiObject
    {
        ["number"] = new OpenApiInteger(123),
        ["value"] = new OpenApiString("sample")
    };

    // 为所有支持的ContentType设置统一示例
    if (op.RequestBody?.Content != null)
    {
        foreach (var contentType in op.RequestBody.Content.Values)
        {
            contentType.Example = sample;
        }
    }

    // 可选：为响应添加示例
    if (op.Responses.TryGetValue("200", out var okResponse))
    {
        var responseSample = new OpenApiObject
        {
            ["id"] = new OpenApiInteger(1),
            ["status"] = new OpenApiString("success")
        };

        foreach (var contentType in okResponse.Content.Values)
        {
            contentType.Example = responseSample;
        }
    }

    return op;
});

关键说明 #

• 自动序列化适配：OpenApiObject是OpenAPI规范的抽象模型，Swagger UI会根据当前选中的MIME类型（JSON/XML等）自动将其序列化为对应格式，无需手动处理每种类型。
• 示例渲染正确：直接赋值给Example属性，而非Examples集合，避免UI将示例拆分为单个属性条目。
• 匹配Schema结构：示例的键值对要和IDictionary<string, object>的Schema对应，确保示例和接口定义的请求体结构一致。

进阶优化：复用示例逻辑 #

如果多个接口需要示例，可以封装成扩展方法简化代码：

public static class OpenApiExtensions
{
    public static OpenApiOperation WithRequestBodySample<T>(this OpenApiOperation op, T sample)
    {
        var json = JsonSerializer.Serialize(sample);
        var openApiSample = OpenApiAnyFactory.CreateFromJson(json);
        
        if (op.RequestBody?.Content != null)
        {
            foreach (var contentType in op.RequestBody.Content.Values)
            {
                contentType.Example = openApiSample;
            }
        }
        return op;
    }
}

使用时直接调用：

.WithOpenApi(op => op.WithRequestBodySample(new { number = 123, value = "sample" }))

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