Postman 实战｜API 文档自动生成与发布

写文档最痛苦的是”代码改了文档没改”。这篇讲让 Postman 根据集合自动出可交互文档，并保持同步。

① 是什么

Postman 能基于集合和示例响应，自动生成 API 文档（Documentation）：每个请求的方法、参数、示例响应都罗列出来，还能在浏览器里直接试调。

② 为什么重要

• 手动维护 Markdown 文档，三天就过期；自动文档跟着集合走，永远最新。
• 可交互文档让前端/第三方不用问你”这个字段叫啥”，自己试就懂。

③ 核心概念拆解

• 自动生成：在集合上开启 Documentation，Postman 据请求定义 + 你填的描述生成页面。
• Markdown 支持：在请求/文件夹的描述里写 Markdown，富文本、代码块都能渲染。
• 交互式文档：读者在文档页填参数直接发请求看真实响应（需你授权/配环境）。
• 版本与定制：支持文档版本；可自定义域名、品牌、可见范围（公开/团队/私有权限）。
• 发布：生成公开链接或发布到团队工作区，更新集合即更新文档。

④ 常见误区

• 误区 1：文档只看请求不看示例。务必保存示例响应，读者才知道返回长啥样。
• 误区 2：描述留空。每个字段写一句，文档才真的”可读”。
• 误区 3：把密钥写进公开文档示例。示例里用脱敏/测试数据。

⑤ 一句话小结

集合即文档源：开启 Documentation、补好描述与示例，Postman 自动产出可交互、常新的 API 文档。

下一篇：API 集成：连接外部平台与系统

参考来源：Mastering Postman, Second Edition（本文为原创讲解，非转载原文）