如何写好API接口文档？

日常项目开发的过程中，接口文档是必不可少的。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口需要文档来说明、系统之间相互调用需要文档来记

开发人员有时会花几周的时间来构建API，也许还要花一星期的时间来编写文档，这可能很耗时。问题是，是否有可能在20分钟内生成API文档？是的，这是可能的，我们现在将学习如何做。

显然，Postman是用于测试API端点的最常用的REST客户端，但是大多数人没有意识到它可以用来生成格式正确的文档。在本教程中，我们将展示一个简单的技巧，说明如何利用Postman减轻生成文档的压力。

在本教程中，我不会介绍如何构建API，假设你已经有现有的API接口和对应端口和参数内容。

利用您现有的请求来生成文档

如果您已经在Postman上测试了接口，那么恭喜您，现在要做的就是回到请求并将它们添加到集合中。

什么是POSTMAN集合

Postman集合使您可以随时重用和共享的方式保存请求，它还允许您对请求进行分组，以便每个API资源都可以像一个文件夹一样在其中保存类似的接口请求。让我们将现有请求添加到集合中。

如何将现有请求添加到集合中。

在现有的请求窗口中，按住Command + S键

点击创建收藏

添加您的首选名称

点击保存按钮

完成上述步骤后，您现在有了一个集合，可以进一步添加您的请求。立即创建一个新集合，它会出现在“集合”选项卡上。

此后，您所需要做的就是将新的或现有的请求添加到集合中。Postman如何为您实现自动化？

标头（可帮助您将所有标头添加到文档中）。

请求主体（发送到端点的JSON请求已复制到您的文档中。

您的请求及其HTTP动词（POST，GET，PUT，PATCH等）将自动为您添加。

您必须自己做什么？

您可以自己为接口请求添加注释，然后将需要的接口转到收藏夹文件夹，并转到任何希望添加描述的请求。

单击编辑选项以向请求添加描述。当您单击编辑链接时，将打开一个新的弹出模式，可以添加描述。

添加您的描述后，点击保存按钮。接下来要做的就是去任何一个要求在您的收藏夹中，并为其添加描述。剩下的一切就是在Postman服务器上发布您的文档。现在转到您的收藏集，然后转到选项菜单。

如果您在生成的文档中发现任何错字，则可以随时返回到集合并进行编辑，但是不要忘记再次发布文档。那么简单的API接口文档就自动生成了～