HTML5注释怎么写API说明_接口注释的必备要素与示例【详解】

絕刀狂花 2026-01-06 00:00:00 次阅读

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) {
  // 实现略
}