接口文档学习及如何写一份优秀的接口文档（转载自@wljslmz && @bsbgjm3j2vy6g）

1. HTTP 请求方式

HTTP（Hypertext Transfer Protocol）是一种在计算机网络中用于传输超媒体文档的应用层协议。HTTP 协议定义了客户端和服务器之间的通信规则，并规定了客户端向服务器发送请求时需要采用的请求方法（请求方式）。

常见的 HTTP 请求方式有四种：

POST（添加）
GET（查询）
DELETE（删除）
PUT（修改）

2. POST 请求

POST 请求用于向指定资源提交数据，通常会导致服务器端的状态发生变化。例如，在 Web 表单中填写用户信息并提交时，就是使用 POST 请求方式将表单数据提交到服务器存储。

使用 POST 请求方式提交的数据会被包含在请求体中，而不像 GET 请求方式那样包含在 URL 中。因此，POST 请求可以提交比 GET 更大的数据量，并且相对更安全。

2.1. 例子

下面是一个 POST 请求的例子：

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 123

{
   "name": "John Doe",
   "email": "johndoe@example.com",
   "age": 30
}

上述代码表示向 example.com 的 /api/user 资源发送一个 POST 请求，请求体中包含了一个 JSON 格式的用户信息。

2.2. 优缺点

POST 请求的优点包括：

可以提交比 GET 更大的数据量。
相对更安全，因为请求参数不会被包含在 URL 中。

POST 请求的缺点包括：

对服务器性能的影响较大。
不适用于对同一资源进行多次操作。

2.3. 应用场景

向服务器提交表单数据。
向服务器上传文件。
创建资源或提交数据到服务器。

3. GET 请求

GET 请求用于向指定资源发出请求，请求中包含了资源的 URL 和请求参数。服务器端通过解析请求参数来返回相应的资源，不会修改服务器端的状态。

使用 GET 请求方式提交的数据会被包含在 URL 中，因此易于被缓存和浏览器保存，但也因此不适合用于提交敏感数据。

3.1. 例子

下面是一个 GET 请求的例子：

GET /api/user?id=123 HTTP/1.1
Host: example.com

上述代码表示向 example.com 的 /api/user 资源发送一个 GET 请求，请求参数中包含了用户的 ID。

3.2. 优缺点

GET 请求的优点包括：

可以被缓存和浏览器保存。
对服务器性能的影响较小。

GET 请求的缺点包括：

不适合用于提交敏感数据。
仅适用于对资源进行查询操作，不能修改服务器端的状态。

3.3. 应用场景

获取资源信息。
对资源进行查询操作。

4. DELETE 请求

DELETE 请求用于请求服务器删除指定的资源，可以理解为对服务器上的资源进行删除操作。使用 DELETE 方式请求会导致指定的资源被永久删除，因此需要谨慎使用。

4.1. 例子

下面是一个 DELETE 请求的例子：

DELETE /api/user?id=123 HTTP/1.1
Host: example.com

上述代码表示向 example.com 的 /api/user 资源发送一个 DELETE 请求，并指定要删除的用户的 ID。

4.2. 优缺点

DELETE 请求的优点包括：

可以永久删除指定的资源。

DELETE 请求的缺点包括：

对服务器性能的影响较大。
不适用于对同一资源进行多次操作。

4.3. 应用场景

删除指定的资源。
按照条件删除一组资源。

5. PUT 请求

PUT 请求用于向服务器更新指定资源，可以理解为对服务器上的资源进行修改操作。使用 PUT 请求方式会覆盖原有的资源内容，因此需要谨慎使用。

5.1. 例子

下面是一个 PUT 请求的例子：

PUT /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 123

{
   "id": 123,
   "name": "John Doe",
   "email": "johndoe@example.com",
   "age": 30
}

上述代码表示向 example.com 的 /api/user 资源发送一个 PUT 请求，并指定要更新的用户信息。

5.2. 优缺点

PUT 请求的优点包括：

可以更新指定的资源。

PUT 请求的缺点包括：

对服务器性能的影响较大。
不适用于对同一资源进行多次操作。

5.3. 应用场景

更新指定的资源。
按照条件更新一组资源。

6. 总结

本文详细介绍了 HTTP 中常见的四种请求方式：POST、GET、DELETE 和 PUT。这四种请求方式各有优缺点，需要根据具体的应用场景选择使用。熟练掌握这些请求方式有助于我们在 Web 服务的开发中更加便捷和高效地实现各种功能。

主要分为以下两个版本，两个版本各有各自的特点，需要应对不同的应用场景

简单版本
复杂版本

简单版本

核心：如果你的案例可以直接依靠复制拿来使用，那这个文档就是好文档

既然要简单，那就抓住核心：怎么简单怎么来，怎么省时间怎么来

如果不知道怎么写，就把案例写的越详细越好。

开发时间是非常宝贵的，而接口对接通常都是一些工期紧张的情况下去快速编写，而且面对一些碎片化的时间工作者，一份简单直观的文档可能更受欢迎。

另外，接口文档最终形式最好是pdf，以前遇到过接口文档写到word里面的，在不同的版本下可能会出现样式等各种问题

最佳方式：word -> pdf

简单版本的目录格式

接口说明
请求示例
请求参数说明
响应示例
响应参数说明

案例模板1：

接口说明：

接口功能：

本接口用于获取用户的token信息。

接口请求地址：

https: xxx/xxx/xxxx
复制代码

请求头 :

请求头	请求内容	说明
Authorization	Basic secretKey	访问token
Content-Type	application/json	请求方式

请求方式: POST

参数类型 ：JSON

请求示例：

绝大多数为json，格式自定

[
    {"id":"20201219",
     "name":"21.59"，
     "age":"ftp_1002"
     ...
    },
    {"id":"20201219",
     "name":"21.59"，
     "age":"ftp_1002"
     ...
    },
]
复制代码

请求参数说明

字段名	字段说明	字段类型	是否必填
字段1	说明字段1的作用	varchar(50)	是
字段2	说明字段2的作用	int	是
字段3	说明字段3的作用	decimal	是

响应示例

成功响应编码：

{
    "code: "200",
    "message": "请求成功",
    "data": 返回数据，格式自定
}
复制代码

失败响应编码：

{
    "code: "200",
    "message": "请求成功",
    "data": 返回数据，格式自定
}
复制代码

响应参数说明

接口返回码	接口返回描述
200	成功
400	请求参数异常
401	授权失败
500	系统异常

案例模板2：

下面这种模板是单个接口的适合很实用，同时针对一些比较简单的接口这样处理还算比较直观

核心是一个表包含所有信息，这对于一些接口量非常非常大的时候或者接口参数相似的时候比较有效果，这样可以使得内容比较紧凑，不会看了下一页忘记上一页的烦恼，当然缺点也很明显，会存在文字堆积的情况。

markdown的表格在存放Json的数据时候不是很直观，建议使用word

接口名	UserUpdateService
接口请求地址	www.baidu.com
功能说明	UserUpdateService接口是应用系统的账号修改方法
请求参数	参数名	中文说明
	RequestId	平台每次调用生成的随机ID，应用系统每次响应返回此ID，String类型
	uid	三方应用系统账号创建时，返回给应用系统的账号主键uid。必传字段
	loginName/ fullName	需要修改的账号字段属性
响应参数	参数名	中文说明
	RequestId	平台每次调用接口发送的请求ID，字段为String类型
	resultCode	接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。
	message	接口调用处理的信息。字段为String类型
请求示例：	{ “token”,””, “treeCode”,” EXECUTIVE”, “code”,””}	markdown展示不是很好看，建议word
返回值	{ “xxxx”: “xxxxxx”, “resultCode”: “0”, “message”: “success” }	markdown展示不是很好看，建议word

案例模板3：

下面这种可能不是很直观，但是参考很多文档发现好像类似的还不少，也可以参考一下。

请求地址：http://www.baidu.com

l 属性列表

属性名	中文命名	值类型	值必须	描述
token	令牌	String	是
treeCode	机构树编码	String	是	如果为空表示根机构，默认填写” ROOT”
code	机构代码	String	是
start_date	开始日期	Date		合同或项目的开始日期
name	机构名称	String	是
end_date	结束日期	Date		合同或项目的结束日期
user_num	驻点人员数量	Int
supplier_name	供应商名称	String
type	机构类型	String	是	项目机构ProjectOrg，行政机构AdministrativeOrg
orgUpCode	上层机构代码	String	是
parentId	父机构code	String	是
isDisabled	是否禁用	Boolean		false

l 响应属性列表

属性名	中文命名	值类型	值必须	描述
code	返回码	String	是
message	返回信息	String	是	如果为空表示根机构，默认填写” ROOT”
data	返回内容	String	是

l JSON数据示例**

[http://xxxxxxxx/xxx/xxx]
请求参数：
"
    {
        “token”,””,               //必填
        “treeCode”,” EXECUTIVE”,  //必填
        “code”,””,                //必填
        “entity”,” {
        "code":"2222",            //必填
        " start_date":"",
        "name":"字段名称",         //必填
        "end_date ":"",   
        "user_num":"",
        "supplier_name":"",
        “type”,””,   //指定类型  
        "orgUpCode":"11111",      //必填
        "parentId":"1111111",    //必填
        “isDisabled”:” false”    //是否禁用
    }
"
响应：login
JSON - 数据示例
{
 "success": true,
 "data": {
     "treeId": "ROOT",
     "parentId": 112034,
     "name": "3333",
 },
 "errorCode": null,
 "errorName": null,
 "errorMessage": null,
 "errorException": {
  "name": null,
  "message": null,
  "trace": null
 }
}
复制代码

至此，一个简单的接口文档差不多就是这些内容，下面将会介绍一下复杂的做法（内容较多）

复杂版本

由于不同的公司有不同的文档格式要求，这里只给出我看过的几个文档罗列下来的一些文档内容，不一定通用，也不一定是很完美的，但是希望内容可以具备一定的参考价值。

复杂版本的内容有点多。请耐心观看或者收藏再看（=v=）

复杂版本的目录格式

+ 封面 + 接口文档名称 + 接口版本号 + 版权说明 + 文档信息 + 标题 | 创建时间 | 打印时间 | 文件名 | 存放目录 | 所有者 | 作用 + 小题：版权声明 + 版本历史（重点1） + \| 版本号 \| 日期 \| 修改者 \| 描述 \| + \| v1.0.0 \| xxx \| xxx \| xxx | + 目录 + 结构清晰 + 有条理 + 能快速定位需要的信息（后文会介绍） + 文档具体内容部分 + 编写目的 + 对接准备事项 + 测试联调 + 上线 + 使用协议 + 规范 + 报文规范 + 请求报文规范 + 响应报文规范 + 接口描述 + 报文规范 + 请求报文 + 响应报文 + 公共报文头 + 接口码说明 + 业务接口 + 查询接口 + 加解密规范 + 原则 + 令牌信息 + 加密规范 + 解密规范 + 业务接口 + 具体接口1： + 说明 + 规范码（查表） + 使用方式 + 请求字段 + 响应字段 + 案例 + 具体接口2…. …….. + 附录 + 参考资料1 + 参考资料2 + 其他….. 复制代码