如何写好API接口文档？( 二 )

标头（可帮助您将所有标头添加到文档中）。
请求主体（发送到端点的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.返回示例
根据实际情况给出请求报文和返回报文的示例；
附录
返回码详细定义。如下所示：

文章插图