补全Description是导出可用文档的前提：请求级填在URL下方文本框（支持Markdown），集合级写清业务目标与适用环境，还需检查参数和Body注释，否则导出显示“no description”。

Postman 里接口没描述，导出的文档就全是 no description，别人根本看不懂你在测什么——补描述不是可选项，是导出可用文档的前提动作。

请求 Description 字段在哪填

它不在 URL 或 Body 里，而是在请求编辑页顶部、URL 输入框正下方那个「Description」文本框里。点击请求进入编辑状态，滚动到最上方就能看到。

• 这个字段支持 Markdown，可以写换行、加粗、列表，比如：## 用途、- 验证用户登录态是否过期
• 别写在 Comments 或 Notes 标签页里——那些内容不会进文档
• 如果用了 Pre-request Script 动态生成参数，建议在 Description 里注明脚本作用，比如：↑ 此请求自动注入 timestamp 和 signature

集合级 Description 怎么写才有效

集合本身的描述会出现在文档首页顶部，是整个模块的“说明书封面”。只写“用户相关接口”这种话等于没写。

• 必须包含：业务目标（如“支撑 App 端手机号一键登录流程”）、适用环境（如“仅限 prod 环境调用，依赖 auth-service v2.3+”）
• 避免堆砌技术词，优先说清楚“谁在什么场景下用这个集合干啥”
• 如果集合含多个子文件夹（Folders），可在 Description 末尾加目录索引，例如：? /login —— 账号登录与 token 刷新

导出前必须检查的三个漏填点

很多人导出 HTML 后才发现关键信息缺失，其实问题都藏在三个地方：

Postman 12.27.7

Postman 12.27.7 Windows x64 官方安装包，适用于 API 设计、调试、测试与协作。该系列包含 Enterprise 云端性能测试静态 IP 出口能力，以及接口规范标签管理改进，适合受限网络测试与规范资源组织场景。

下载

• Request 级别的 Description：每个请求都得有，空着就显示 no description
• Params 列表里的每项 Parameter 的 Description 字段：鼠标悬停在参数名右侧的 ⓘ 图标上才能编辑，不填就看不到参数用途
• Body 中 JSON 字段的注释：虽然 Postman 不直接支持字段级描述，但你可以在 Body 的 raw 内容开头加 Markdown 注释块，比如：/* {"uid": "用户唯一标识，长度 32 位字符串"} */

为什么 Description 影响自动化测试脚本可维护性

当别人基于你的 Collection 写 Tests 脚本时，Description 是他们理解预期行为的第一依据。比如一个返回 401 的请求，如果 Description 写的是 "验证非法 token 被拒绝" ，那测试断言就该检查 responseCode.code === 401；如果只写 "登录失败"，别人可能误判为密码错，去断言响应体里的 message 字段。

更隐蔽的问题是：Postman 的 Collection Runner 在批量执行时，如果某个请求的 Description 里明确写了 ⚠️ 仅限测试环境运行，团队成员扫一眼就能避开线上误操作——这种提示比藏在 Pre-request Script 注释里可靠得多。