---

name: api-xml-comments

description: API 接口 XML 注释规范与模板。在新增或修改后端 API、为接口方法编写或补全 XML 注释时使用。

API 接口 XML 注释规范

何时使用

• 新增或修改后端 API 接口时
• 为接口方法补全或统一 XML 注释时
• 代码审查要求接口注释符合规范时

---

标准格式

所有 API 接口方法必须按以下格式编写 XML 注释：

/// <summary>
/// 接口功能描述（简洁明了的一句话）
/// </summary>
/// <remarks>
/// 详细功能说明和使用场景
///
/// 示例请求：
/// ```json
/// {
///   "参数名": "参数值",
///   "参数名2": "参数值2"
/// }
/// ```
///
/// 参数说明：
/// - 参数名: 参数描述
/// - 参数名2: 参数描述
/// </remarks>
/// <param name="参数名">参数描述</param>
/// <returns>返回值描述</returns>
/// <response code="200">成功响应描述</response>
/// <response code="400">错误响应描述</response>
/// <response code="500">服务器错误描述</response>

---

注释要求

• <summary>：一句话概括功能，简洁明了
• <remarks>：详细说明、示例请求（JSON）、参数说明列表
• 示例请求使用 JSON 格式，参数说明用列表
• 必须包含所有可能返回的 HTTP 状态码（200/400/500 等）的 <response> 说明
• 复杂接口必须提供完整请求示例