如何为OpenAPI/Swagger生成的接口JSON添加类字段描述信息

你之前使用的[Description]特性默认不会被Swagger/OpenAPI生成器读取，可根据需求选择以下两种方案实现：

方案1：使用Swagger专属标注特性（无需额外配置，适合零散标注） #

如果你的项目用的是主流的Swashbuckle.AspNetCore包，直接替换原有[Description]为[SwaggerSchema]特性即可：

public class Customer
{
    [JsonRequired]
    [SwaggerSchema(Description = "This is my foo foo foo")]
    public string CustomerId { get; set; }
}

如果你使用的是v5之前的旧版Swashbuckle，对应特性为[Schema(Description = "你的描述内容")]

方案2：启用XML文档注释（适合全项目批量生成，无需单独加特性） #

该方案可以直接读取代码里的三斜杠注释自动生成描述，不需要额外给每个属性加特性，配置步骤如下：

1. 右键你的项目 → 选择「属性」→「生成」→ 勾选「XML文档文件」，配置同时对Debug、Release模式生效，自动生成的路径无需修改
2. 在服务注册代码中添加XML注释读取配置，示例（.NET 6+的Program.cs）：

builder.Services.AddSwaggerGen(options =>
{
    // 获取当前程序集生成的XML注释文件路径
    var xmlFileName = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFullPath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    // 第二个参数传入true，代表同时读取模型类的属性注释
    options.IncludeXmlComments(xmlFullPath, true);
});

3. 之后直接给属性加三斜杠XML注释即可：

public class Customer
{
    [JsonRequired]
    /// <summary>
    /// This is my foo foo foo
    /// </summary>
    public string CustomerId { get; set; }
}

以上两种方案生成的Swagger/OpenApi JSON都会自动带上你需要的description字段。

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