Swashbuckle .NET Core下能否在Swagger UI参数区展示请求体对象

问题排查与解决方案 #

实现效果的配置步骤 #

你要的效果完全可以实现，按以下步骤操作即可：

• 开启XML注释加载
  首先确保项目开启了XML文档生成：右键你的Web API项目→选择「属性」→切换到「生成」选项卡→在「输出」区域勾选「XML文档文件」，同时在「禁止显示警告」栏添加1591;，避免无注释的代码触发编译警告。
  之后在服务注册部分添加XML注释加载逻辑，.NET 6+的Program.cs示例如下：

using System.Reflection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// 其他服务注册...

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    
    // 加载当前项目生成的XML注释文件
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    // 第二个参数设为true会同时加载控制器和模型的注释
    options.IncludeXmlComments(xmlFilePath, true);
});

• 配置序列化为OpenAPI V2格式
  如果要实现你提到的SerializeAsV2对应的效果，直接在Swagger中间件配置中开启即可，示例如下：

var app = builder.Build();

// 其他中间件配置...

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(options =>
    {
        // 开启后Swagger会按OpenAPI V2规范生成文档，请求体结构会展示在Parameters区域
        options.SerializeAsV2 = true;
    });
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "你的API名称 v1");
    });
}

// 其他中间件配置...
app.Run();

补充说明 #

如果不开启SerializeAsV2，默认的OpenAPI V3规范会将请求体单独放在「Request Body」区域展示结构，不会合并到Parameters区域，两种方式都可以正常展示请求对象的字段、注释和示例值，根据你的使用习惯选择即可。
配置完成后重新编译运行项目，即可看到TestObject的结构和字段注释正常展示在对应的区域。

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