HTML5注释写API说明的必备要素与示例

HTML5的注释（）本质上只是静态标记，既不会被浏览器执行，也无法被JavaScript读取或文档工具识别，因此绝不能用作API说明——它既无法保障接口契约与代码的一致性，又违背关注点分离原则，还容易在构建过程中被误删。真正有效的API注释必须紧贴可执行逻辑：写在JS函数上方的JSDoc、TS类型声明旁的/** */描述，或后端路由文件中的结构化注释（如Swagger或Pydantic），才能被工具自动提取、校验并生成权威文档；若确需在HTML中体现接口信息，唯一推荐方式是通过

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 里体现接口信息，只推荐一种安全方式

用