.NET API文档如何自定义请求示例并实现请求响应属性差异化？

针对你提出的两个需求，我整理了WebAPI开发中常用的落地方案，都是经过实践验证的可行做法：

一、自定义API文档的请求示例（以Swashbuckle/Swagger为例） #

WebAPI生态里最常用的文档工具是Swashbuckle（对应Swagger UI），要让文档显示你在XML注释里写的自定义JSON示例，按以下步骤配置即可：

步骤1：开启XML文档生成 #

打开项目属性的「生成」选项卡，勾选「XML文档文件」，指定生成路径（比如bin\Debug\net472\YourProject.xml，根据你的.NET版本调整路径）。

步骤2：配置Swashbuckle读取XML注释 #

.NET Framework WebAPI

在SwaggerConfig.cs中添加配置：

GlobalConfiguration.Configuration
    .EnableSwagger(c =>
    {
        c.SingleApiVersion("v1", "你的API名称");
        // 引入生成的XML注释文件
        var xmlPath = System.Web.HttpContext.Current.Server.MapPath("~/bin/YourProject.xml");
        c.IncludeXmlComments(xmlPath);
        // 启用读取XML注释中的<example>标签
        c.OperationFilter<ExamplesOperationFilter>();
    })
    .EnableSwaggerUi();

需要先安装Swashbuckle.Examples NuGet包来支持示例过滤。

.NET Core WebAPI

在Program.cs中配置：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API", Version = "v1" });
    // 自动获取XML注释文件路径
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
    // 启用示例解析支持
    c.ExampleFilters();
});

需要安装Swashbuckle.AspNetCore.Filters NuGet包。

步骤3：验证自定义示例生效 #

你已经在接口的XML注释里写好了<example>标签，只要Swashbuckle正确读取XML注释，Swagger UI就会显示你自定义的JSON示例，而不是默认的模型序列化值。

二、实现请求隐藏last_log_time但响应显示 #

不能用[IgnoreDataMember]的话，有两种优雅的解决方案：

方案1：使用Json.NET条件忽略（推荐，无需新增类） #

如果你的WebAPI默认使用Json.NET作为序列化器（绝大多数场景都是），可以利用JsonIgnoreCondition特性精准控制序列化行为：

public class Job {
    [Required(AllowEmptyStrings = false)]
    [Range(1, Int64.MaxValue)]
    public Int64 info_id { get; set; }
    public Int64? some_other_id{ get; set; }
    
    // 反序列化（读取请求）时忽略该属性，序列化（返回响应）时正常输出
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenReading)]
    public DateTime last_log_time { get; set; }
}

这个特性需要Json.NET 12.0.1及以上版本，既能阻止客户端传入的last_log_time被绑定到模型，又能在响应中正常返回该属性的值。

方案2：拆分请求/响应模型（更清晰，符合单一职责） #

如果不想依赖特定版本的Json.NET，最稳妥的方式是拆分模型：

• 创建JobRequest作为请求接收模型（不含last_log_time）
• 原Job类作为响应返回模型（保留所有属性）

代码示例：

// 请求专用模型
public class JobRequest {
    [Required(AllowEmptyStrings = false)]
    [Range(1, Int64.MaxValue)]
    public Int64 info_id { get; set; }
    public Int64? some_other_id{ get; set; }
}

// 原Job类作为响应模型
public class Job {
    public Int64 info_id { get; set; }
    public Int64? some_other_id{ get; set; }
    public DateTime last_log_time { get; set; }
}

// 接口修改为接收JobRequest
[HttpPost]
[Route("api/job/update")]
public IHttpActionResult Update(JobRequest request) {
    // 转换为Job实体处理业务逻辑
    var job = new Job {
        info_id = request.info_id,
        some_other_id = request.some_other_id,
        last_log_time = DateTime.Now // 示例赋值，实际根据业务逻辑设置
    };
    // 响应返回完整Job对象
    return Ok(job);
}

这种方式边界清晰，避免了模型职责混杂，也不会有序列化配置的依赖问题。

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