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

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

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

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

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

什么是POSTMAN集合

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

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

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

点击创建收藏

添加您的首选名称

点击保存按钮

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

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

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

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

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

您必须自己做什么？

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

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

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

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

网友二：

API规范

1.接口名称

统一使用小写，如：order/query

2.uri

提供全路径，如：https://www.toutiao.com/order/query

3.请求协议

http还是https

4.请求方法

get还是post方式

5.请求消息头

公共的头部参数，如版本，加密，加签，压缩算法，时间戳等

6.请求参数

消息体，相关业务参数，根据实际业务说明

7.应答消息头

公共的头部参数，如版本，加密，加签，压缩算法，时间戳等

8.应答参数列表

消息体，相关业务参数，根据实际业务说明

9.返回示例

根据实际情况给出请求报文和返回报文的示例；

附录

返回码详细定义，如下所示：

网友三：

你好，我是一名全栈开发工程师，我就说说如何写好API接口及文档供第三方或者其他同时调用。

首先我们谈谈API接口的规范：

1.首先接口要设置统一的返回规范，例如：

1. { "code": "200", 
2.  
3. "msg": "成功", 
4.  
5. "data": { 
6.  
7. "userId": "0d67cfa7-f6a1-46b6-8e5a-b605afc98c44", 
8.  
9. "username": "ww", 
10.  
11. "password": "123456", 
12.  
13. "status": 0, 
14.  
15. "createTime": 310863886132307, 
16.  
17. "updateTime": 312955781619836 
18.  
19. } 
20.  
21. } 

要设置统计：code返回状态码，msg返回消息，data返回数据

{ "code": "500", "msg": "用户保存过程中发生异常,请检查！", "data": null }

2.接口要注意保密性

对于接口使用的访问，我们要使用认证授权，不可以不认证授权就可以获取数据，对于一些人员信息敏感数据，和财务数据泄露，会造成极大损失。

对于加密，我们可以使用AES加密算法，RSA加密算法，Base64加密算法，MD5加密算法等。

3.对于授权认证

基于表单的认证（Cookie & Session）：基于表单的认证并不是在HTTP协议中定义的，而是服务器自己实现的认证方式，安全程度取决于实现程度。一般用Cookie来管理Session会话，是最常用的认证方式之一。它的安全程度取决于服务器的实现程度，客户端在Cookie中携带认证信息，服务器解析并返回结果。

基于JWT(Json Web Token)的认证：App和服务端常用的认证方式，用户ID和密码传输到服务器上验证，服务器验证通过以后生成加密的JWT Token返回给客户端，客户端再发起请求时携带返回的Token进行认证。

Http Basic认证：最早的Http认证方式，用户ID和密码以分号连接，经过Base64编码后存储到Authorization字段，发送到服务端进行认证 ；用户ID/密码以明文形式暴露在网络上，安全性较差。

Http Digest认证：在HttpBasic的基础上，进行了一些安全性的改造，用户ID, 密码 , 服务器/客户端随机数，域，请求信息，经过MD5加密后存储到Authorization字段，发送到服务端进行认证；密码经过MD5加密，安全性比Basic略高。

其他认证方式（Oauth认证，单点登陆，HMAC认证）：通过特定的加密字段和加密流程，对客户端和服务端的信息进行加密生成认证字段，放在Authorization或者是消息体里来实现客户信息的认证。

认证和授权是API安全的前提，一个安全的API应该有能力识别调用它的系统和终端用户的身份。

4.就是接口文档

(1).Swagger2 自动生成接口文档

(2).apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释

(3).ShowDoc的api开放功能 自动生成api文档

网友四：

接口文档的好坏，对于对接人员来说还是还是很重要的，作为前端开发人员，后端给的接口很乱会让我更乱，所以写好一个接口文档是非常重要的，下面就来谈谈写好一个接口文档应该注意哪些方面

接口名称

这里统一使用小写 如:api/order/get

可参考跟着Github学习Restful HTTP API 设计

url提供客户端使用的全路径

如http://127.0.0.1:8080/api/order/get

请求协议

Http,Https

请求方式

POST,GET等

头部(系统参数)

加密签名,时间戳等

请求参数(业务)

业务相关的输入参数

响应参数(业务)

输出参数

返回示例

定义返回结果数据结构,更直观

1.返回成功

2.返回失败

网友五：

我做的多是项目组内部的api.一般都是一demo加上几句简单说明。

demo是js和ajax的

原生的很好理解。

内容是json,结构就放说明里头。

见过有生成工具的，说明丢注释里头生成出来，也是不错的做法，适合工作量大的项目。

网友六：

如何编写一份好的API文档，需要：

文档规划

明确API文档的基本内容

要保持一致，避免行话

包括交互式示例和其他资源

维护API文档

使用Baklib组织目录，文档层级分明，结构清晰有逻辑，给用户和开发人员更好的阅读体验。

更多内容可以查看：http://wiki.baklib.com/kaikai/f71b

Baklib使用链接：https://www.baklib.com?utm_campaign=1&utm_content=e7734791-1341-4bcf-9271-6da9a65e84dd&utm_term=22

网友七：

可以试试ApiPost。

以下2步让您初步体验ApiPost的魅力！

1. API写完想要测试？试试模拟发送一次请求

新建接口，我想模拟发送请求如下

1. curl --location --request POST 'https://echo.apipost.cn/get.php?c=Course&id=1000' \ 
2.  
3. --header 'User-Agent: Apipost client Runtime/+https://www.apipost.cn/' \ 
4.  
5. --header 'Content-Type: application/json' \ 
6.  
7. --data '{ "course_id":1 }' 

如图进行进行配置：

点击发送，查看接口返回结果：

你可以查看返回数据，返回Header、Cookie、状态码、请求时长等等数据。

2. 测试完后我想快速生成文档给前端看

点击分享文档

复制并打开文档地址就可以看到了完整的接口文档。

3. 后记

恭喜你体验了第一个接口文档的旅程。我们的工具同时节省了前后端的开发以及沟通时间。

除此之外我们还有更多更好的功能等您来体验。

Tags: 怎么写好api接口文档 如何写好api接口文档

分享到：