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

前言：

最近看了很多写的十分好的接口文档，在了解业务方面给了十分多的帮忙，解决很多时候对于一些 协商数据 的问题困扰，同时，后续集体的工作当中，也须要对外开放接口给第三方进行调用，这时候一个好的标准文档能够解决很多问题。

文章目标：

1. 集体对于写接口文档的一些材料整顿。
2. 学习如何写一份他人乐意去看的文档。
3. 心愿能够通过本文帮忙解决那些面临本人写接口文档的状况下无从下手的难堪的场面。

目录：

次要分为以下两个版本，两个版本各有各自的特点，须要应答不同的利用场景

1. 简略版本
2. 简单版本

简略版本

外围：如果你的案例能够间接依附复制拿来应用，那这个文档就是好文档

既然要简略，那就抓住外围：怎么简略怎么来，怎么省工夫怎么来

如果不晓得怎么写，就 把案例写的越具体越好。

开发工夫是十分贵重的，而接口对接通常都是一些工期缓和的状况上来疾速编写，而且面对一些碎片化的工夫工作者，一份简略直观的文档可能更受欢迎。

另外，接口文档最终模式最好是 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，替换生产环境账户明码，替换密钥为生产密钥等等

应用协定 + 标准：

能够是本次对接应用的算法，通信协议，能够是术语阐明或者和业务相干的其余阐明，以及对接的要求都能够，施展空间很大，自在设计。

报文标准：

报文标准是接口对接的外围局部，因为对接大部分的工夫根本都是花在接口参数调试和申请调试等。所以报文标准算是十分重要的内容。具体内容能够参考简略版本的接口形容，也能够应用目录格局进行对应的形容

  + 申请报文：次要为申请的 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 公里 吧。慢慢来 ……