十年架构师告诉你怎样写好接口文档

　　前言：
　　最近看了很多写的非常好的接口文档，在理解业务方面给了非常多的帮助，解决很多时候对于一些协商数据的问题困扰，同时，后续个人的工作当中，也需要对外开放接口给第三方进行调用，这时候一个好的规范文档可以解决很多问题。文章目的：
　　1.个人对于写接口文档的一些资料整理。
　　2.学习如何写一份别人乐意去看的文档。
　　3.希望可以通过本文帮助处理那些面临自己写接口文档的情况下无从下手的尴尬的局面。接口文档书写
　　1. 前置描述
　　●产品文档，简单说明背景，接口用来干嘛的
　　●技术文档，说一说各方的具体实现，复杂的可以说下具体的设计思路，n个方案对比，贴上sql，ddl，dml设计，具体代码等具体能看的东西
　　2. 方法概览
　　●方法路径，命名统一
　　●方法名称，命名统一
　　●方法类型 get/post…
　　3. 参数定义
　　●参数命名统一，下划线，驼峰…
　　●类型定义明确，整形，长整型，浮点，对象，指针
　　●是否需要枚举 required Enuma a
　　●是否必填 optional int a //非必填
　　●必要备注，说明这个字段是干啥的 required int a //不能叫a
　　●是否需要默认值 required int a =0
　　●如果是比较难懂的字段，贴上相关说明链接 required int a //字段说明http:heheda.com
　　●如果是部分有特殊意义的string或者数组，举例子说明含义，比如 yyyy-mm-dd类型的string
　　●需要提供idl文件的或者webservice，注意格式化
　　●http请求可以给到示范的请求返回
　　●如果是接口变更，用特殊标记表示，比如字体加红简单版本
　　核心：如果你的案例可以直接依靠复制拿来使用，那这个文档就是好文档
　　既然要简单，那就抓住核心：怎么简单怎么来，怎么省时间怎么来
　　如果不知道怎么写，就把案例写的越详细越好。
　　开发时间是非常宝贵的，而接口对接通常都是一些工期紧张的情况下去快速编写，而且面对一些碎片化的时间工作者，一份简单直观的文档可能更受欢迎。
　　另外，接口文档最终形式最好是pdf，以前遇到过接口文档写到word里面的，在不同的版本下可能会出现样式等各种问题最佳方式：word -> pdf
　　简单版本的目录格式
　　●接口说明
　　●请求示例
　　●请求参数说明
　　●响应示例
　　●响应参数说明案例模板1：
　　接口说明：
　　接口功能：本接口用于获取用户的token信息。
　　接口请求地址：https: xxx/xxx/xxxx
　　请求头 :
　　请求方式: POST
　　参数类型 ：JSON
　　请求示例：
　　绝大多数为json，格式自定[
　　{＂id＂:＂20201219＂,
　　＂name＂:＂21.59＂，
　　＂age＂:＂ftp_1002＂
　　...
　　},
　　{＂id＂:＂20201219＂,
　　＂name＂:＂21.59＂，
　　＂age＂:＂ftp_1002＂
　　...
　　},
　　]
　　请求参数说明
　　响应示例
　　成功响应编码：{
　　＂code: ＂200＂,
　　＂message＂: ＂请求成功＂,
　　＂data＂: 返回数据，格式自定
　　}
　　失败响应编码：{
　　＂code: ＂200＂,
　　＂message＂: ＂请求成功＂,
　　＂data＂: 返回数据，格式自定
　　}
　　响应参数说明
　　接口返回码 接口返回描述
　　案例模板2：
　　下面这种模板是单个接口的适合很实用，同时针对一些比较简单的接口这样处理还算比较直观
　　核心是一个表包含所有信息，这对于一些接口量非常非常大的时候或者接口参数相似的时候比较有效果，这样可以使得内容比较紧凑，不会看了下一页忘记上一页的烦恼，当然缺点也很明显，会存在文字堆积的情况。markdown的表格在存放Json的数据时候不是很直观，建议使用 word
　　案例模板3：
　　下面这种可能不是很直观，但是参考很多文档发现好像类似的还不少，也可以参考一下。
　　请求地址：http://www.baidu.com
　　l 属性列表
　　l 响应属性列表
　　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
　　+ 其他.....
　　案例：
　　封面：
　　封面还是比较重要的，毕竟是打开文档的第一眼内容，下面用阿里的文档作为参考，可以看到封面一般是如下内容：
　　●公司名称
　　●文档名称
　　●版本号
　　文档信息：
　　文档信息主要记录这份文件的产生日期以及具体的创建打印日期等。
　　版权声明：（现在这个时代版权是极其重要的）
　　xxxx所有，不得三方借阅、出让、出版
　　版本历史：
　　版本历史是很重要的，每次改动都需要有详细的记录，这样才能保证文档的干净和有效，同时可以方便review的时候，对于文档的修订者进行文档审查
　　版本号 日期 概述 修订者
　　目录：
　　好的文档一定有好的目录，只要按照一定的规范和格式写出来的文档，一般看上去都是十分舒服的。还是用阿里的开发手册做参考文档具体内容部分
　　这一部分发挥的自由空间就比较大了，不同的业务不同的公司不同的需求不同的人都能写出万千种格式的文档，所以这里也是给一个样例做参考使用。是否有实用价值因人而异。为了不让整个目录树太长，这里没有做标题说明=-=
　　编写目的：
　　需要解决什么问题，为什么要这份文档，这份文档有什么参考价值？
　　对接准备事项：
　　接口方可以提供什么内容，接口方需要对接方的那些内容，以及提供的其他信息，比如需要对接方提供 系统应用id，系统唯一标识。向对接方提供密钥等等
　　​ 1. 测试联调：分配测试的密钥，测试环境的账户和密码以及其他信息
　　​ 2. 上线：上线之后需要做什么事情，如：替换生产url，替换生产环境账户密码，替换密钥为生产密钥等等
　　使用协议 + 规范：
　　可以是本次对接使用的算法，通信协议，可以是术语说明或者和业务相关的其他说明，以及对接的要求都可以，发挥空间很大，自由设计。
　　报文规范：
　　报文规范是接口对接的核心部分，因为对接大部分的时间基本都是花在接口参数调试和请求调试等。所以报文规范算是非常重要的内容。具体内容可以参考简单版本的接口描述，也可以使用目录格式进行对应的描述
　　加解密规范：
　　也是比较重要的部分，也是比较花时间的地方，需要大量调试来打通接口的地方，存在以下的几个要点
　　●原则：接口存在一些简单的原则，比如非对称加密，数字签名，时间戳判断有效性，具体按照接口的原则自由设置
　　●令牌信息：描述令牌是如何生成的，是比较重要的部分，一般由对接双方沟通完成，最好多以案例和代码辅助解释
　　●加密规范：描述接口数据的加密过程，比较重要的内容信息，最好多以案例和代码辅助解释
　　●解密规范：就是解释接口要如何解密，比如需要拿到服务端给过来的配对公钥才能解密，再比如使用签名+参数进行对照加密验证签名是否正确等。
　　加解密规范参考：
　　一般的加密方式，一般情况下做到下面这种形式基本可以屏蔽大部分的攻击：
　　按照map的key进行字典排序，同时加入timetamp值校验核对时间
　　把参数按照一些特殊形式拼接为key=value&key=value的形式，末尾带入时间戳或者其他的一些信息，比如应用Id等核实身份的内容
　　把这一串按照AES加密，然后按照BASE64编码，生成一个编码串
　　把BASE64编码进行MD5加密，加密完成之后，得到固定长度的MD5字符串
　　按照md5串+上面的string在进行一次md5加密，生成签名，那么这个签名基本上就唯一的业务接口
　　这里基本可以照抄简单接口模板，因为接口描述每个人的描述不同，下面给出一些基本上涉及的点，另外，到了这一步就尽量用案例辅助，因为案例可以帮助接口阅读者更快速的上手和理解，注意这一部分的内容：实用性大于理论性
　　具体接口：
　　1.说明
　　2.规范码（查表）
　　3.使用方式
　　4.请求字段
　　5.响应字段
　　6.案例
　　附录：
　　可能这部分和说明书一样基本没人看，所以不做过多的解释，个人到目前为止看过的接口文档基本没有遇到附录写的很详细的，这里可以随意施展。 ​本文到此结束！好看的皮囊千篇一律、有趣的灵魂万里挑一，创作不易，离不开宝子们的支持，喜欢的朋友点点赞和关注！感谢支持！