如何写好API接口文档？
▍ℑ如何写好API接口文档？
日常项目开发的过程中，接口文档是必不可少的。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口需要文档来说明、系统之间相互调用需要文档来记录接口协议等等。对于一个完整的项目，接口文档是至关重要的。那我们如何写好一份接口文档呢？今天就让我们说一说接口文档几个重要的要素。
1、接口概述
接口概述主要说明本接口文档涉及到的业务功能点，面向的阅读对象以及接口文档主要包括哪些业务的接口，可以让读者有一个直观的认识。如：本文档定义了中台系统面向外部接入方的数据协议接口，主要包括：用户注册接口、同步用户、授权认证等接口。适合阅读的对象为接入中台开发者或者外部合作方…。这样的一段描述，对于阅读者来说可以对整个接口文档有一个大概的认识。
2、权限说明
有的接口调用需要授权认证，在这部分需要进行说明。如果接口只是基于分配的token认证，那文档需要说明token的获取方式。如果接口需要进行签名认证，需要在这里说明签名的具体方法，如下图：
sign参数的生成规则要具体说明，最好能示例说明，如：
这样接入方可以验证自己的签名方式是否正确。
3、编码方式
接口的请求过程中可能由于编码导致乱码，所以，接口必须约定编码方式，参考以下写法：
4、请求说明
接口文档的请求说明中主要说明接口请求的域名以及请求的数据格式：如
5、接口列表
接口列表是接口文档的主要内容，这部分内容需要列出所有的接口名称、接口地址、接口的请求方式、接口的请求参数以及响应格式。在接口的请求参数中我们需要说明每个参数的含义、类型以及是否必须等属性。对于接口响应结果，如果有业务字段，也需要进行说明。下面是一个比较完整的示例：
6、状态码说明
接口的响应体一般都会带有响应的状态码，例如成功、失败等。状态码有助于接入方进行接口调用状态的判断。如：
接口文档如果能体现出以上几个要素，那可以算是一个完整的接口文档，对于接入方来说可以很好的阅读理解。
▍Ⓕ如何写好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接口文档就自动生成了～
▍～如何写好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接口及文档供第三方或者其他同时调用。
首先我们谈谈API接口的规范：
1.首先接口要设置统一的返回规范，例如：
{ "code": "200",
"msg": "成功",
"data": {
"userId": "0d67cfa7-f6a1-46b6-8e5a-b605afc98c44",
"username": "ww",
"password": "123456",
"status": 0,
"createTime": 310863886132307,
"updateTime": 312955781619836
}
}
要设置统计：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接口文档？
swagger告别手写文档，前后端分离开发也能一建生成api 手写api文档太low了
------------------
推荐阅读：
我腰椎做微创手术快三个月了，腰一直还痛，下床活动一二个小时腰就撑不住痛了怎么办？
下一篇： 金陵十二钗正册都有谁？
