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

# API 接口 XML 注释规范

## 何时使用

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

---

## 标准格式

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

```csharp
/// <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>` 说明
- 复杂接口必须提供完整请求示例