ASP.NET Web Application API如何添加Swagger字段注释？

步骤1：启用项目的XML注释生成 #

右键你的ASP.NET Web Application API项目 → 属性 → 切换到生成标签页 → 在输出区域勾选「XML文档文件」，默认路径为bin\你的项目名称.xml。如果不想看到未添加注释的警告，可在「抑制特定警告」中输入1591。

步骤2：配置Swagger读取XML注释文件 #

打开项目中App_Start目录下的SwaggerConfig.cs，找到GlobalConfiguration.Configuration.EnableSwagger()的配置块，添加读取XML文件的代码：

// 获取当前程序集的XML注释文件路径
var xmlFileName = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlFilePath = System.IO.Path.Combine(System.Web.HttpContext.Current.Server.MapPath("~/bin"), xmlFileName);

// 让Swagger加载该XML文件
c.IncludeXmlComments(xmlFilePath);

步骤3：为字段、模型和API添加注释 #

直接在对应的字段、模型类或API方法上方添加XML注释即可：

// 模型类示例
public class UserInfo
{
    /// <summary>
    /// 用户唯一标识ID
    /// </summary>
    public int UserId { get; set; }

    /// <summary>
    /// 用户昵称
    /// </summary>
    public string NickName { get; set; }
}

// API控制器方法示例
/// <summary>
/// 根据用户ID查询用户信息
/// </summary>
/// <param name="userId">要查询的用户ID</param>
/// <returns>用户信息实体</returns>
public IHttpActionResult GetUserInfo(int userId)
{
    // 业务逻辑代码
    return Ok(new UserInfo { UserId = userId, NickName = "测试用户" });
}

步骤4：验证效果 #

重新生成项目并启动API，打开Swagger页面，就能看到字段、模型和API方法的注释已经显示在对应的位置了。

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