ASP.NET Core 9 Minimal API中添加OpenAPI请求体示例不显示的问题排查

看起来你遇到的问题是手动添加的请求体示例没有出现在生成的OpenAPI规范中，这主要是因为你直接替换了整个RequestBody对象，而没有在框架自动生成的请求体结构基础上进行修改。让我们一步步解决这个问题：

问题根源 #

当你在WithOpenApi中执行operation.RequestBody = new OpenApiRequestBody { ... }时，你完全替换了框架自动生成的请求体对象。虽然框架后续会自动补充Schema的引用，但你的示例配置可能没有被正确保留，或者在框架的处理流程中被覆盖了。框架默认会基于你的WeatherForecast记录自动生成请求体的Schema结构，直接替换整个RequestBody会破坏这种自动关联，导致示例无法正常展示。

修复方案 #

正确的做法是修改框架已经自动生成的RequestBody内容，而不是重新创建一个新的对象。这样既能保留自动生成的Schema引用，又能成功添加你自定义的示例。

修改后的完整代码如下：

using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.MapPost("/weatherforecast", (WeatherForecast weatherForecast) => Results.Ok())
   .WithName("Add WeatherForecast")
   .WithOpenApi(operation => 
   {
       // 检查自动生成的请求体和application/json媒体类型是否存在
       if (operation.RequestBody?.Content.TryGetValue("application/json", out var mediaType) == true)
       {
           // 直接在已有的媒体类型上添加示例
           mediaType.Example = new OpenApiObject
           {
               ["date"] = new OpenApiString("2025-07-10"),
               ["temperatureC"] = new OpenApiInteger(25),
               ["summary"] = new OpenApiString("Sunny")
           };
       }
       return operation;
   });

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

验证修改效果 #

重新运行应用后，访问/openapi/v1.json，你会看到请求体的application/json节点下已经包含了你的示例内容：

"/weatherforecast": {
  "post": {
    "tags": [ "WebApplication4" ],
    "operationId": "Add WeatherForecast",
    "requestBody": {
      "content": {
        "application/json": {
          "schema": { "$ref": "#/components/schemas/WeatherForecast" },
          "example": {
            "date": "2025-07-10",
            "temperatureC": 25,
            "summary": "Sunny"
          }
        }
      },
      "required": true
    },
    "responses": { "200": { "description": "OK" } }
  }
}

额外说明 #

如果你需要添加多个示例，可以使用mediaType.Examples属性（复数），它接受一个键值对集合，每个键对应一个示例的名称，值是包含Summary、Description和Value的OpenApiExample对象，适合展示不同场景下的请求体示例。

内容来源于stack exchange