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

案例：

封面：

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

• 公司名称
• 文档名称
• 版本号

文档信息：

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

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

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

版本历史：

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

目录：

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

文档具体内容部分

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

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

编写目的：

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

对接准备事项：

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

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

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

使用协议 + 规范：

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

报文规范：

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

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

加解密规范：

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

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

加解密规范参考：

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

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

业务接口

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

具体接口：

1. 说明
2. 规范码（查表）
3. 使用方式
4. 请求字段
5. 响应字段
6. 案例

附录：

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

总结：

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

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

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

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

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