接口文档如何编写，Java 接口文档编写方法

小编在项目开发过程中，与很多的企业对接过接口，包括一些小企业定制化的软件接口，也包括一些大厂形成规范的接口，相对来说，很多小厂的接口编写比较随意，而大厂对接口的定义就比较严谨，接下来我们就来分析一下。

1、api接口签名

有过开发经验的程序猿，一般都会注意到这个问题，为了接口的安全性，需要对参数进行签名，防止参数在请求过程中被篡改。就类似于你的一个好久没联系的朋友或者同学，通过微信或者QQ，给你发了条消息，向你借钱，有一部分人的第一反应是他是不是被盗号了？他是本人吗？所以我们建议通过视频或者电话再沟通核实一遍，这就是为了安全性防止财产的损失。

（1）为什么需要 API 接口签名？

对外开放的 API 接口都会面临一些安全问题，例如伪装攻击、篡改攻击、重放攻击以及数据信息泄露的风险。利用 API 接口签名能方便的防范这些安全问题和风险。在设计 API 接口签名时主要考虑以下几点：

保证请求数据正确

当请求中的某一个字段的值变化时，原有的签名结果就会发生变化。所以，只要参数发生变化，签名就要发生变化，否则请求将会是一个无效的请求。

保证请求来源合法

一般情况下，生成签名的算法都会成对出现一个 appKey 和一个 appSecret，根据 appKey 能识别出调用者身份；根据 appSecret 能识别出签名是否合法。

这两个参数是非必须的，根据平台的商户定，比如如果平台没有商户的概念或者只有一个商户，像我们常见的自己的客户端对接自己的服务端。但是像一些提供接入能力的平台，比如微信，很多企业都可以接入，那他就需要区分不同的商户，每个商户分配一个appId，然后再通过appKey+appSecret来区分调用者的权限。

• 识别接口的时效性

一般情况下，签名和参数中会包含时间戳，这样服务端就可以验证客户端请求是否在有效时间内，从而避免接口被长时间地重复调用。

（2）签名实现逻辑

各家在签名时的请求参数可能有一点差别，但整体实现逻辑是类似的。

第一步：将除sign外的所有请求参数放入集合Map中；

第二步： 将第一步得到的集合M中的参数按照参数名ASCII码从小到大排序（字典序）;

第三步：将第二步中排序后的key和与之对应的value拼接起来，使用URL键值对的格式（即key1=value1&key2=value2…）得到字符串 params；

第四步：在params的最后再拼接appKey密钥，然后通过某种加密算法或通过hash算法得到 sign 值（一般为Base64(HMAC_SHA1(params, appSecret))）；

第五步：sign加到params 中，将params放入请求头中发送请求目标接口；

（3）签名实现代码

我们会常用到几个参数：

version：版本号

charset ：字符编码

sign_type：签名类型，如RSA、RSA2、SHA

timestamp：当前时间戳，格式YYYYMMDDhhmmss，在服务端会验证比对请求方的时间与系统当前时间差，若超出太多，比如超过十分钟，就认为这个是过期的请求，不允许获取数据。

nonce_str：随机字符串，随机以主要保证签名不可预测。每次请求时都不一样。

2、加密算法

对于一些比较敏感的私人信息，接口传输过程最好进行加密传输，比如用户姓名、手机号、身份证号码等。如果需要明文保存，可以使用AES双向加密解密，如果直接保存加密的数据，可以使用md5加密。

（1）md5加密

MD5加密是一种不可逆的加密算法，不可逆加密算法的特征是加密过程中不需要使用密钥，输入明文后由系统直接经过加密算法处理成密文，这种加密后的数据是无法被解密的，只有重新输入明文，并再次经过同样不可逆的加密算法处理，得到相同的加密密文并被系统重新识别后，才能真正解密。很多网站为了安全性，会额外再加一个盐值（一串随机字符串）一起进行加密，提高加密的安全性。MD5盐值加密作用就是为了防止MD5被暴力破解。通过盐值和密码进行组合计算得出MD5，在数据库中要同时存储该MD5码及盐值。在需要验证密码正确性时，可以将密码和数据库中对应账号密码的盐值组合计算出的MD5与数据库中的MD5进行比对。

另外一些网站号称可以对md5加密的密文进行解密，他们只是手机了足够多的密码信息，来进行匹配，反向推导出加密前的明文，实际上是无法真正的实现md5解密的。

（2）AES双向对称加解密

AES是一种分组密码 分组长度为128位（16字节），根据密钥长度可分为AES-128 AES-192和AES-256，密钥长度不同，AES的加密轮数也不同。

AES的工作模式分为ECB、CBC、CFB等

ECB是最简单和最早的模式，首先是密钥扩展，将加密的数据按照16字节的大小分成若干组，对每组都用同样的密钥加密。

CBC和ECB的区别就是添加了一个初始向量（16字节），在将密钥分成若干组之后，第一组与初始化向量异或之后再进行与ECB相同的加密流程，后面的每一组都与上一组的密文进行异或之后再与密钥加密。

3、编码解码

（1）为什么会出现乱码

在计算机中，不管是一段文字、一张图片还是一段视频，最终都是以二进制的方式来存储。也就是最终都会转化为 0001 1000 这样的格式。换句话说，计算机只认识 0 和 1 这样的数字，并不能直接存储字符。所以我们需要告诉它什么样的字符对应的是什么数字。但是如果用户A定义的编码规则，传到B使用了另外一套解码规则进行解码，由于编码和解码的规则对应不上就导致了乱码。

（2）怎么解决乱码

这就需要我们了解java中的编码转换。双方定义好编码方式，我们以utf8和gbk这两种常见的编码为例。

4、接口token鉴权

有一部分人会把token鉴权和接口加签搞混，我们来梳理一下这两种方式。

使用Sign签名，是为了对接口参数进行验证，我们在业务开发过程中与上下游系统进行接口对接时，常采用这种方式，那为什么不是token方式呢，因为我们不需要登录上下游系统，他们在拦截器层面已经放行了这些接口，不需要登陆后才给调用。而像我们管理平台上的接口，比如查询某个列表的数据，就不能直接调用接口，需要先登录系统才有调用接口的权限。

Token是用来判断用户身份的一个标识，身份验证通过了，才能调用接口，token也是一种加密方式，使用用户的信息进行加密，一般可以使用md5加密，我们来看以下token鉴权的过程。

第一步：用户使用账号密码登录，向服务端发起http请求

第二步：服务端校验账号密码数据

第三步：验证成功后，服务端会生成一个token，并将这个token返回给客户端

第四步：客户端收到这token后将它放在cookie或者本地存储

第五步：客户端再次向服务器发起请求时带上token

第六步：服务端收到请求，然后验证客户端请求里面带着token来判断权限，如果验证成功，就向客户端返回请求的数据。

5、Java 接口文档编写

（1）概述