17370845950

HTML5中注释不能用作API注释，因其被浏览器忽略、JS无法读取、文档工具不识别；有效API注释应写在JS函数上方（JSDoc）、TS类型声明旁或后端路由文件中，或通过嵌入结构化元数据。

HTML5 本身没有“API 注释语法”—— 只是普通注释，浏览器完全忽略，也不会被 JS 引擎或文档生成工具（如 JSDoc、TypeDoc）识别为接口说明。

HTML 中的 不能当 API 注释用

很多人误以为在 HTML 文件里写 就能生成接口文档，实际不会生效。HTML 注释仅用于标记页面结构、临时禁用代码块或给团队成员留便签，不具备语义化描述能力。

• 所有 内容在 DOM 中不可见，JS 无法读取
• 主流文档工具（JSDoc、ESDoc、Swagger UI）不解析 HTML 注释
• 若把接口定义写在 HTML 里，会导致逻辑与视图耦合，违反关注点分离原则

真正有效的 API 接口注释该写在哪

接口契约必须和可执行代码绑定，才能保障一致性。正确位置只有三个：

• JavaScript 函数上方：用 JSDoc 格式写在 function 或 export 前，配合 /** */
• TypeScript 接口/类型声明旁：用 /** */ 描述 interface 或 type 的用途和字段含义
• 后端路由文件中：如 Express + Swagger-UI 使用 @openapi 注释块，或 FastAPI 的 docstring + Pydantic model 注释

例如前端调用接口的函数注释：

/**
 * 获取用户详情
 * @param {string} userId - 用户唯一标识，长度 12~32 位字母数字组合
 * @returns {Promise<{name: string, email: string}>} 用户基本信息对象
 * @throws {Error} 当 userId 格式错误或服务返回 404 时抛出
 */
export async function fetchUser(userId) {
  // 实现略
}

如果非要在 HTML 里体现接口信息，只推荐一种安全方式

用 嵌入结构化元数据，而不是注释。这种方式可被 JS 读取、校验，也能被构建工具提取。

• 不污染 HTML 主体结构
• 避免注释被压缩工具（如 html-minifier）意外删掉
• 支持 JSON Schema 验证字段必填性、类型、格式

示例：

真正的接口文档从来不是靠 HTML 注释撑起来的；它依赖代码即文档（Code as Documentation）的实践——注释必须紧贴实现、可验证、可提取。把 API 说明塞进 里，等于把钥匙焊死在门框上，门没开，人先迷路了。