postman 里面的注释，主要作用是给请求集合 接口 环境变量 脚本添加说明文字，方便团队多人协作的时候看懂接口用途 参数含义 调用注意事项，postman 注释分为集合注释 请求注释 文件夹注释 代码脚本注释四大类，很多新手只知道发请求测试接口，不知道添加注释，等到团队交接或者隔一段时间回头看接口，就完全忘记这个接口是做什么的，postman 原生支持在集合和请求层面添加描述注释，同时在前置脚本 后置断言脚本里面，还可以使用代码注释语法，也就是 javascript 的注释写法，合理写注释可以提升接口文档可读性，还能一键生成接口文档，是后端测试 前端联调必备操作，注释不会影响接口实际发送请求，不会修改请求参数，只是纯说明文本。

postman 本身是接口调试工具，底层脚本引擎是 javascript，所以脚本区域的注释语法和 javascript 保持一致，单行注释用双斜杠，多行注释用斜杠加星号包裹，而集合和请求的描述框属于富文本注释，支持换行 列表 简单格式，不需要特殊符号语法，两种注释形式不要搞混，富文本注释是给人阅读的说明，脚本注释是写给代码看的说明，脚本注释在运行的时候会被引擎直接忽略，不会执行里面内容。

基础信息表格

注释详细分类讲解

第一种 集合与文件夹富文本注释

打开 postman 左侧侧边栏，找到对应集合或者文件夹，点击右侧描述入口，就可以输入注释内容，可以写模块介绍 接口负责人 更新时间 公共请求头说明，这个注释内容后续可以通过 export 导出，或者直接发布成 postman 在线文档，团队成员打开集合就能看到。

第二种 单个请求描述注释

点开单个接口请求，在请求名称下方找到 Description 描述框，在这里填写注释，内容一般写接口名称 请求方式 请求地址 接口作用 必填参数 错误码说明 返回示例，这个是最常用的注释，联调的时候前端打开接口，直接看描述就知道怎么调用。

第三种 脚本代码注释

前置脚本 Pre Request Script 和后置 Tests 断言脚本，使用 javascript 注释规范

单行注释 双斜杠后面写说明，适合短说明

多行注释 斜杠星号开头，星号斜杠结尾，适合大段说明文字

操作步骤

第一步，打开 postman，在左侧找到目标集合或者接口请求

第二步，点击描述 Description 输入框，进入富文本注释编辑页面

第三步，输入接口说明内容，保存之后注释就会绑定在这个请求或者集合上

第四步，如果需要给脚本添加注释，切换到 Pre Request Script 或者 Tests 标签页，在代码里面添加双斜杠单行注释或者多行块注释

第五步，保存请求，之后可以尝试导出集合或者发布文档，验证注释内容是否正常显示

注释编写规范清单

第一，注释写清楚接口功能，不要只写测试接口这种无意义文字

第二，参数注释要标注参数名 参数类型 是否必填 参数含义

第三，更新接口之后同步更新注释，避免注释和实际接口不一致

第四，脚本注释不要写和代码无关的冗余内容，保持简洁

第五，团队项目统一注释格式，方便所有人阅读

补充注意事项

清单

第一，postman 富文本注释是保存在集合数据里面，如果单独导出请求，注释会跟着一起导出

第二，postman 新版部分版本，请求名称旁边的描述入口位置有微调，但是功能不变

第三，脚本注释不会参与接口请求，不会改变请求结果，也不会触发断言

第四，不要把敏感账号密码写在注释里面，发布公开文档会泄露信息

综合总结，postman 注释分为富文本描述注释和脚本代码注释，富文本注释用来写接口文档说明，脚本注释遵循 javascript 语法，写注释可以方便团队联调，还支持导出在线接口文档，是 postman 接口项目管理非常重要的功能。

【常见问题】

问题 1 postman 的注释 脚本里面单行注释怎么写

回答 1 postman 的注释，脚本区域是 javascript 语法，单行 postman 的注释使用双斜杠，斜杠后面直接写说明文字，代码运行的时候会自动忽略这一行注释。

问题 2 postman 的注释 能不能导出到接口文档

回答 2 postman 的注释可以导出，写在 Description 里面的 postman 的注释，在导出集合或者发布 postman 在线文档的时候，注释内容会同步带出，适合团队生成接口文档。

问题 3 postman 的注释 会不会影响接口请求结果

回答 3 postman 的注释不会影响接口请求结果，不管是富文本描述注释还是脚本里面的 postman 的注释，都只是说明内容，发送请求的时候不会执行注释，接口返回结果不受注释影响。

问题 4 postman 的注释 多行注释语法是什么

回答 4 postman 的注释，脚本区域多行 postman 的注释使用斜杠加星号开始，星号加斜杠结束，中间可以写多行说明，适合长段代码说明。

【免责申明】

本内容基于 postman 通用版本功能讲解，软件版本更新之后界面入口和功能可能发生调整，操作方式请以当前安装版本官方说明为准，本内容不构成商业项目规范强制标准。