前言:
最近看了很多写的非常好的接口文档,在理解业务方面给了非常多的帮助,解决很多时候对于一些协商数据
的问题困扰,同时,后续个人的工作当中,也需要对外开放接口给第三方进行调用,这时候一个好的规范文档可以解决很多问题。
文章目的:
- 个人对于写接口文档的一些资料整理。
- 学习如何写一份别人乐意去看的文档。
- 希望可以通过本文帮助处理那些面临自己写接口文档的情况下无从下手的尴尬的局面。
目录:
主要分为以下两个版本,两个版本各有各自的特点,需要应对不同的应用场景
- 简单版本
- 复杂版本
简单版本
核心:如果你的案例可以直接依靠复制拿来使用,那这个文档就是好文档
既然要简单,那就抓住核心:怎么简单怎么来,怎么省时间怎么来
如果不知道怎么写,就把案例写的越详细越好。
开发时间是非常宝贵的,而接口对接通常都是一些工期紧张的情况下去快速编写,而且面对一些碎片化的时间工作者,一份简单直观的文档可能更受欢迎。
另外,接口文档最终形式最好是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 + 其他..... 复制代码