首页 慕课教程 Postman 教程 Postman 教程 使用 Postman 发布接口

使用 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 文档的定制、发布和分享,以及如何查看其他人分享的文档。

图片描述