在 Linux 上使用 Postman 编写与发布 API 文档
一 环境准备与安装
- 在 Linux 上安装 Postman：从官网下载 Linux 版本安装包（.tar.gz），解压至 /opt，并创建符号链接以便启动：
- 解压：
tar -xvf Postman-linux-x64-<version>.tar.gz -C /opt
- 链接：
sudo ln -s /opt/Postman/Postman /usr/local/bin/postman
- 启动后进入 Postman 主界面，准备创建集合与编写文档。
二 编写高质量文档的核心步骤
- 创建 Collection（集合）：用于组织同一模块或服务的所有接口，添加集合级 描述 说明用途与范围。
- 添加 Request（请求）：在集合中新增接口，填写 URL、HTTP 方法、Headers、Body 等。
- 完善 文档字段：在每个请求的 Description 中写清功能、权限、注意事项；在 Params/Headers/Body 中为各字段补充 名称、类型、是否必填、示例、约束。
- 生成 示例响应：发送请求后将实际响应保存为 示例（Examples），至少包含 成功、失败、异常 场景，便于使用者快速理解返回结构。
- 结构化管理：通过 文件夹（Folder） 对接口按业务域或版本拆分，保持文档层次清晰、易于维护。
三 预览发布与导出分享
- 在线预览：在集合菜单中选择 View in Web，以网页形式查看包含示例与描述的文档，适合快速校对与内部分享。
- 发布文档：在集合右上角或集合选项里选择 Publish Docs，生成可公开访问的 公共 URL，团队成员或外部开发者可直接查看最新文档。
- 导出与分享：
- 导出为 JSON 集合：便于团队成员导入 Postman 复用请求与示例。
- 导出为 Markdown：在集合详情选择 Export，勾选 包含示例 与 包含描述，生成 Markdown 文件用于仓库或静态站点托管。
四 协作与自动化建议
- 用 环境变量 管理不同环境（如 dev/staging/prod）的 Base URL、鉴权 Token，文档中统一引用变量名，避免硬编码，减少维护成本。
- 在集合上编写 测试脚本（Tests） 做自动化校验，配合 Collection Runner 定期回归，确保文档与实现一致；必要时将 请求导出为 curl 供服务端或运维调试。
- 文档即代码：将导出的 JSON 集合 纳入 Git 版本管理，与接口变更同步评审与发布，保证文档持续可用与可追溯。
