Postman 能帮助开发者测试 API,还能方便地生成 API 文档,生成 API 文档有助于团队协作和接口分享,提高开发效率。本文将介绍如何使用 Postman 生成和发布 API 文档,让你的 API 更加规范、易于维护和使用,并介绍另一种更强大的生成 API 文档的方法。
步骤 1:选择需要生成文档的 Collection
首先,打开 Postman 并选择你已经创建好并包含多个请求的 Collection。在左侧栏中找到你的 Collection,点击选中它。然后,在 Collection 的右侧,你会看到一个包含三个点的按钮,点击它然后选择“View documentation”选项。
![Postman 如何生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-108.png)
步骤 2:选择“Publish”
点击“View documentation”后,你会看到当前集合的所有接口都生成在了一个文档里面,你可以在这里添加一些属于 API 文档的描述,然后点击右上角的“Publish ”按钮,可将生成的文档发布并分享。
![Postman 如何生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-109.png)
步骤 3:设置 API 文档基本信息
进入“Publish Docs”界面后,你需要填写 API 文档的一些基本信息,生成的 API 文档会根据这些信息来组织内容,也可帮助访问者快速了解这个 API 集合的用途和内容。
![Postman 如何生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-110.png)
步骤 4:点击“Publish”发布
设置完基本信息后,检查其他选项是否需要调整,通常默认设置已经足够。确认无误后,点击页面底部的“Publish ”按钮。
![Postman 如何生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-111.png)
步骤 5:生成的文档链接
点击“Publish”按钮后,Postman 会自动生成一个文档链接。这个链接可以直接复制并分享给你的团队成员或其他 API 使用者。
![Postman 如何生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-112.png)
通过以上步骤,你已经成功生成并发布了你的 API 文档。不过生成的文档是公开的,似乎不能设置权限(截止到目前),所以,我更推荐使用 Apifox 来生成 API 文档,Apifox 可以导出 Swagger、Markdown 等格式的接口文档,还可以在线分享 API 文档并根据需要自定义域名、设置权限等。
使用 Apifox 生成 API 文档
如果你想尝试更便捷、高效的方式来调试(管理) API,那么可以使用 Apifox。Apifox 提供了直观的界面和 IDEA 插件,让你轻松管理项目接口。Apifox 是集成了 API 文档、API 调试、API Mock、API 自动化测试的 API 一体化协作平台。
你可以在 Apifox 中导出 HTML、Markdown 等格式 API 文档。在 Apifox 中打开项目,然后点击页面左侧边栏的【项目设置->导出数据】选项,接着选择“Markdown”格式。你可以选择导出全部接口或者部分接口,也可以通过标签来筛选接口,接着选择运行环境,点击“导出”按钮即可完成导出。Apifox 会生成一个.md
格式的文件,你可以将其下载到本地。
![生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-113.png)
文档导出后,你可以使用一些工具(如 MarkText)打开查看效果,还不错,对吧!
![生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-114.png)
如果想将接口文档在线分享给其它人看,我们一般推荐你使用【在线分享】的方式,这种方式,只要一个链接就可以在浏览器中打开,可以设置权限、过期时间,还可以直接调试,更加方便,快去试试吧!
![生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-115.png)
![生成 API 文档](https://apifox.com/apiskills/content/images/2024/06/image-116.png)
总结
通过 Postman,你不仅可以方便地测试 API,还能轻松生成 API 文档,促进团队协作和接口分享。本文详细介绍了如何使用 Postman 生成和发布 API 文档,并推荐了功能更强大的 Apifox 作为替代方案,帮助你更高效地管理和分享 API,推荐使用!