使用 Postman 发布接口

1. 前言

你可以自动生成 Postman API 文档，可以私下分享文档，或者在 web 上发布文档。Postman 基于集合生成和托管文档，实时同步并可以通过浏览器访问。你可以使用该文档与团队成员或合作伙伴协作。

2. 生成文档

文档都是基于集合的，所以你可以为一个已存在的集合创建文档，也可以将文档依赖于某个集合。

2.1 给已存在的集合创建文档

要在 Postman 给一个已存在的集合创建文档，先选择集合，然后点击图中向右箭头的按钮：

然后点击“在 web 查看 (view in web)”就可以在 web 打开文档：

Tips：你可以在 Postman 或者 web 上直接更改文档。

另外一种创建文档的方式是，点击 New -> API Documentation -> Select an existing collection -> 选择集合：

3. 发布文档

你可以发布 API 文档对公众可见，这样，任何拥有该链接的人都可以查看它。发布的文档让大家了解怎么使用你的 API 以及 API 的详细信息，包括参数，请求和响应体和示例代码；

你的文档是实时更新的根据你集合的状态，所以你不用每次都重复发布流程去更新你的文档。

文档中包含一个“在 Postman 运行 (Run in Postman)”按钮用户就可以直接在 Postman 中运行该 API。例如， 请参考 Postman API 文档。 将你的文档添加到 API网络和模板中也可以让你的集合在 Postman 中可用，例如帮助开发者接受和采用。

3.1 发布文档的方法

右键点击集合( collections )，然后点击发布文档（Publish Docs）：

发布成功之后，浏览器上会有一个 URL， 通过这个 URL 你就可以看到这个集合的 API 文档，真的很简单：

Tips：环境中人和机密信息(e.g. 密码和访问令牌)都可能在发布文档时公开可见，所以在发布文档之前要确保环境中不包含任何机密信息

3.2 定制化文档

Tips：你可以选择为你发布的文档选择一个域名。

你可以为你的 API 文档配置背景色，代码背景和高亮颜色。还可以为你的文档选择默认布局，比如单列或者双列视图。当然你还可以更改和预览这些设置会在发布时如何显示。

3.3 分享文档

要把文档分享给你的用户或者其他 Postman 社区中的人，那么请开启集合可查“Collection discovery”功能。这能让你的文档通过 Postman API 网络和模板变得可查可用。

Tips：当你把文档公开发布之后，任何拿到 URL 的人都可以访问。

• 选择添加到 API 网络( Add to API Network) 让你的文档在 Postman 发布网络中可查可用；
• 选择添加到 Postman 模板( Add to Postman Templates) 可以把你的集合分享到 Postman 社区

4. 查看文档

你可以查看分享给你的任何集合的文档。拥有查看权限的 Postman 团队、业务和企业成员可以查看和评论文档；拥有编辑权限的这些成员可以修改和更新文档。

当你通过点击在网页查看( View in web) 打开 API 文档：

打开之后，在顶部可以看到一些配置选项，可以选择环境( environment ), 布局( layout )：

还能看到每个请求的详细信息，包括示例代码，要求的授权类型， URL， 描述，请求和响应结构。

5. 小结

API 生成之后，重点还是在于怎么去查看和应用；这篇文章主要讲述 API 文档的定制、发布和分享，以及如何查看其他人分享的文档。