如何写一份优秀的接口文档

[TOC]

前言：

最近看了很多写的非常好的接口文档，在理解业务方面给了非常多的帮助，解决很多时候对于一些协商数据的问题困扰，同时，后续个人的工作当中，也需要对外开放接口给第三方进行调用，这时候一个好的规范文档可以解决很多问题。

文章目的：

个人对于写接口文档的一些资料整理。
学习如何写一份别人乐意去看的文档。
希望可以通过本文帮助处理那些面临自己写接口文档的情况下无从下手的尴尬的局面。

简单版本

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

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

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

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

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

最佳方式：word -> pdf

简单版本的目录格式

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

案例模板1：

接口说明：

接口功能：

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

接口请求地址：

1	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
接口请求地址	http://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
  + 其他.....

案例：

封面：

封面还是比较重要的，毕竟是打开文档的第一眼内容，下面用阿里的文档作为参考，可以看到封面一般是如下内容：

公司名称
文档名称
版本号

文档信息：

文档信息主要记录这份文件的产生日期以及具体的创建打印日期等。

文档名	内容
标题	一份帅气的文档
创建日期	20xx-xx-xx
打印日期	20xx-xx-xx
文件名	文档的全名
存放目录	文件位置
所有者	某某公司
作者	张三

版权声明：（现在这个时代版权是极其重要的）

xxxx所有，不得三方借阅、出让、出版

版本历史：

版本历史是很重要的，每次改动都需要有详细的记录，这样才能保证文档的干净和有效，同时可以方便review的时候，对于文档的修订者进行文档审查

版本号	日期	概述	修订者
1.0.0	20xx-xx-xx	创建	张三
1.0.1	20xx-xx-xx	修改文档第一小节内容	李四
1.0.2	20xx-xx-xx	修订文档第四小节的错误描述，更新文档说明	王五

好的文档一定有好的目录，只要按照一定的规范和格式写出来的文档，一般看上去都是十分舒服的。还是用阿里的开发手册做参考

文档具体内容部分

这一部分发挥的自由空间就比较大了，不同的业务不同的公司不同的需求不同的人都能写出万千种格式的文档，所以这里也是给一个样例做参考使用。是否有实用价值因人而异。

为了不让整个目录树太长，这里没有做标题说明=-=

编写目的：

需要解决什么问题，为什么要这份文档，这份文档有什么参考价值？

对接准备事项：

接口方可以提供什么内容，接口方需要对接方的那些内容，以及提供的其他信息，比如需要对接方提供 系统应用id，系统唯一标识。向对接方提供密钥等等

1. **测试联调**：分配测试的密钥，测试环境的账户和密码以及其他信息

2. **上线**：上线之后需要做什么事情，如：替换生产url，替换生产环境账户密码，替换密钥为生产密钥等等

使用协议 + 规范：

可以是本次对接使用的算法，通信协议，可以是术语说明或者和业务相关的其他说明，以及对接的要求都可以，发挥空间很大，自由设计。

报文规范：

报文规范是接口对接的核心部分，因为对接大部分的时间基本都是花在接口参数调试和请求调试等。所以报文规范算是非常重要的内容。具体内容可以参考简单版本的接口描述，也可以使用目录格式进行对应的描述

+ 请求报文：主要为请求的Body,以及请求的header内容，一般都是Json的格式，并且要求UTF8编码
+ 响应报文：返回的格式和内容，也是需要协商的部分
+ 公共报文头：一般需要重复使用的参数可以作为公共报文头，但是不是所有的公共报文头都是必选，存在可选的参数
+ 接口码说明：描述接口的注意事项，以及那些字段参数需要重点关注，主要为提示信息
+ 业务接口：一般表示业务的返回结果，比如统一2000作为报文的成功响应码，其他所有码都是存在对应的接口码表进行设计。
+ 查询接口：如何才算是表示查询成功，比如一个还钱的接口当中可能是受理中，拒绝或者处理完成，等查询接口的信息描述

加解密规范：

也是比较重要的部分，也是比较花时间的地方，需要大量调试来打通接口的地方，存在以下的几个要点

原则：接口存在一些简单的原则，比如非对称加密，数字签名，时间戳判断有效性，具体按照接口的原则自由设置
令牌信息：描述令牌是如何生成的，是比较重要的部分，一般由对接双方沟通完成，最好多以案例和代码辅助解释
加密规范：描述接口数据的加密过程，比较重要的内容信息，最好多以案例和代码辅助解释
解密规范：就是解释接口要如何解密，比如需要拿到服务端给过来的配对公钥才能解密，再比如使用签名+参数进行对照加密验证签名是否正确等。

加解密规范参考：

一般的加密方式，一般情况下做到下面这种形式基本可以屏蔽大部分的攻击：

按照map的key进行字典排序，同时加入timetamp值校验核对时间
把参数按照一些特殊形式拼接为key=value&key=value的形式，末尾带入时间戳或者其他的一些信息，比如应用Id等核实身份的内容
把这一串按照AES加密，然后按照BASE64编码，生成一个编码串
把BASE64编码进行MD5加密，加密完成之后，得到固定长度的MD5字符串
按照md5串+上面的string在进行一次md5加密，生成签名，那么这个签名基本上就唯一的

业务接口

这里基本可以照抄简单接口模板，因为接口描述每个人的描述不同，下面给出一些基本上涉及的点，另外，到了这一步就尽量用案例辅助，因为案例可以帮助接口阅读者更快速的上手和理解，注意这一部分的内容：实用性大于理论性

具体接口：

说明
规范码（查表）
使用方式
请求字段
响应字段
案例

附录：

可能这部分和说明书一样基本没人看，所以不做过多的解释，个人到目前为止看过的接口文档基本没有遇到附录写的很详细的，这里可以随意施展。

总结：

本篇文章将接口文档分为两种模式来讲解：

简单版本：核心是 怎么简单怎么来，如何工程紧或者非常讨厌写文的人可以使用这种方式，优点是出货速度快，缺点嘛，简单的东西可能造成很多细节的忽略，有时候写文的人也会忽略，所以还是需要多注意一下不要直接CV
复杂版本：我想基本没几个人想写这种复杂文档，一份文档写下来基本半天没了，

个人还是非常喜欢写文档的，一方面是写文档可以提高自己的文档功底，同时和费曼学习法的方式十分的贴切，可以通过写作来回顾和总结思路过程，另一方面，一份好文档真的可以省未来的时间成本，想象一下如何你可以在当别人来问你就甩一份文档解决问题的时候，可以给自己大量的时间减少自己的沟通成本，对于日常工作中被打断思路再常见不过了，用文档记录的形式记录可能在以后要回过来改代码的救一命。

有点跑偏了，总之，这篇文章更多的目的是分享自己对于文档编写的一些个人思考，个人从实习公司到转正写了个把月文档，过程十分的枯燥乏味单调，但是当回过头来看到自己的成果的时候。还是蛮有成就感了。

这是今年最后一篇文章了，个人选择锻炼给自己做未来投资，下面截个图给自己留念一下，争取年前跑满100公里吧。慢慢来……

爱看书的阿东

如何写一份优秀的接口文档

如何写一份优秀的接口文档

前言：

文章目的：

目录：

简单版本

简单版本的目录格式

案例模板1：

接口说明：

请求示例：

请求参数说明

响应示例

响应参数说明

案例模板2：

案例模板3：

l 属性列表

l JSON数据示例**

复杂版本

复杂版本的目录格式

案例：

封面：

文档信息：

版本历史：

文档具体内容部分

加解密规范参考：

总结：