如何写好API接口文档？

试试语音读文章

热门回答：

日常项目开发的过程中。接口文档是必不可少的。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口需要文档来说明、系统之间相互调用需要文档来记录接口协议等等。对于一个完整的项目。接口文档是至关重要的。那我们如何写好一份接口文档呢？今天就让我们说一说接口文档几个重要的要素。

1、接口概述

接口概述主要说明本接口文档涉及到的业务功能点。面向的阅读对象以及接口文档主要包括哪些业务的接口。可以让读者有一个直观的认识。如：本文档定义了中台系统面向外部接入方的数据协议接口。主要包括：用户注册接口、同步用户、授权认证等接口。适合阅读的对象为接入中台开发者或者外部合作方…。这样的一段描述。对于阅读者来说可以对整个接口文档有一个大概的认识。

2、权限说明

有的接口调用需要授权认证。在这部分需要进行说明。如果接口只是基于分配的token认证。那文档需要说明token的获取方式。如果接口需要进行签名认证。需要在这里说明签名的具体方法。如下图：

sign参数的生成规则要具体说明。最好能示例说明。如：

这样接入方可以验证自己的签名方式是否正确。

3、编码方式

接口的请求过程中可能由于编码导致乱码。所以。接口必须约定编码方式。参考以下写法：

4、请求说明

接口文档的请求说明中主要说明接口请求的域名以及请求的数据格式：如

5、接口列表

接口列表是接口文档的主要内容。这部分内容需要列出所有的接口名称、接口地址、接口的请求方式、接口的请求参数以及响应格式。在接口的请求参数中我们需要说明每个参数的含义、类型以及是否必须等属性。对于接口响应结果。如果有业务字段。也需要进行说明。下面是一个比较完整的示例：

6、状态码说明

接口的响应体一般都会带有响应的状态码。例如成功、失败等。状态码有助于接入方进行接口调用状态的判断。如：

接口文档如果能体现出以上几个要素。那可以算是一个完整的接口文档。对于接入方来说可以很好的阅读理解。

其他观点：

开发人员有时会花几周的时间来构建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.返回示例

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

附录

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

• 准备与好友合伙做生意,开什么店合适？
• 想开个店,开什么好呢？资金不多,刚刚创业。谢谢？
• 有什么行业适用于初创业？
• 刚入社会的人想开店,最好开一家什么店？
• 我是一个创业小白,想要开一家店铺,大家有什么好的推荐吗？

以上就是由互联网推广工程师 网创网 整理编辑的，如果觉得有帮助欢迎收藏转发~