ASP.NET Core 3 HttpPost接口Swagger如何显示请求示例值代替JSON Schema

ASP.NET Core 3 中可通过以下两种方式为Swagger请求参数添加自定义示例值：

方法一：XML注释+Example标签（推荐） #

操作简单，无需额外编写业务代码，直接在模型类上添加注释即可。

1. 给Employee类的属性添加带<example>标签的XML注释，示例代码如下：

/// <summary>
/// 员工请求入参
/// </summary>
public class Employee
{
    /// <summary>
    /// 参数1
    /// </summary>
    /// <example>张三</example>
    public string parameter1 { get; set; }
    /// <summary>
    /// 参数2
    /// </summary>
    /// <example>研发部</example>
    public string parameter2 { get; set; }
    /// <summary>
    /// 参数3
    /// </summary>
    /// <example>13800138000</example>
    public string parameter3 { get; set; }
    /// <summary>
    /// 参数4
    /// </summary>
    /// <example>zhangsan@company.com</example>
    public string parameter4 { get; set; }
    /// <summary>
    /// 参数5
    /// </summary>
    /// <example>28</example>
    public int parameter5 { get; set; }
    /// <summary>
    /// 参数6
    /// </summary>
    /// <example>3</example>
    public int parameter6 { get; set; }
}

2. 开启项目XML文档生成：
   • 右键项目 → 选择「属性」→ 切换到「生成」标签
   • 找到「输出」板块，勾选「XML文档文件」，路径使用默认生成的即可
   • 在「禁止显示警告」输入框中添加1591，避免无注释属性触发编译警告
3. 配置Swagger服务读取XML注释，修改Startup.cs中ConfigureServices方法的Swagger配置：

using System.Reflection;
using System.IO;

public void ConfigureServices(IServiceCollection services)
{
    // 其他服务配置省略
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的接口文档名称", Version = "v1" });
        // 读取当前项目的XML注释文件
        var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
        // 第二个参数设为true表示读取模型类的注释
        c.IncludeXmlComments(xmlFilePath, true);
    });
}

方法二：自定义ISchemaFilter（适合复杂示例场景） #

如果需要动态生成示例、或者示例逻辑较为复杂，可通过自定义Schema过滤器实现。

1. 新建EmployeeSchemaFilter类，实现ISchemaFilter接口：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class EmployeeSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 仅匹配Employee类型设置示例
        if (context.Type == typeof(Employee))
        {
            schema.Example = new OpenApiObject
            {
                ["parameter1"] = new OpenApiString("张三"),
                ["parameter2"] = new OpenApiString("研发部"),
                ["parameter3"] = new OpenApiString("13800138000"),
                ["parameter4"] = new OpenApiString("zhangsan@company.com"),
                ["parameter5"] = new OpenApiInteger(28),
                ["parameter6"] = new OpenApiInteger(3)
            };
        }
    }
}

2. 在Swagger配置中注册自定义过滤器，修改Startup.cs的AddSwaggerGen配置：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的接口文档名称", Version = "v1" });
    // 注册自定义Schema过滤器
    c.SchemaFilter<EmployeeSchemaFilter>();
});

完成以上任意一种方法配置后，重新编译运行项目，Swagger的Post接口请求区域就会展示你设置的实际示例值，而非默认的Schema类型说明。

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