接口文档笔记

开发肯定少不了接口文档。
虽然编写接口文档要费一些时间，但当客户找你要接口文档，子系统对接时，你自己排查问题时，就会发现有一份完整的接口文档的好处。

版本变更记录

版本变更记录很必要。
1、自己查看的时候比较方便。
2、用户拿到新版本的文档，看变更记录就知道改了哪些点，可以有重点的get到有用信息。

例如：

版本号	拟制/修改日	拟制/修改人	修改记录	批准人
v1.0.1	2020-03-04	诸葛亮	新增了2个接口 接口1 接口2	-
v1.0.2	2020-05-01	张良	接口2参数修改	-

接口列表

接口1

接口编号+接口名称

例如 3.3.1 用户查询接口

请求描述

–	–
请求地址	http://prd-domain.net/crm/api/findUser 生产环境 http://sit-domain.net/crm/api/findUser 测试环境
请求方式	HTTP POST
入参类型	JSON
出参类型	JSON

入参字段

序号	输入项	类型	是否必填	字段含义	备注
1	username	VARCHAR2(255)	是	用户名
1	orgName	VARCHAR2(255)	否	用户名

字段类型这里可填的方式有2种：
1、string，double等。
2、如果对接方要根据接口文档进行数据库设计。那么用数据库的字段形式更好，如：
VARCHAR2(255), DECIMAL。

入参格式1

参数名称 参数描述 参数类型 是否必填 示例值

注：参数描述和示例值 可以放到一起，例如 使用标志[Y:是,N否]

带长度的入参格式

ID 类型 长度 是否必须 描述

注：类型和长度时间也可以写在一起，例如String(32)或varchar2(32) 大家都知道什么意思。

最佳入参格式

入参报文可以用json输出空字符串，这样就不用拼接报文了

详见json博客

那么明细呢? 实际即使设置了为空，空list也不会输出，要么给list设置个有值对象。
或者直接拿list的类单独打印也行。

出参字段

略

请求报文示例

{
	"username":"",
	"orgName":"11474798",   
	"pageNo": 1,
	"pageSize": 20
}

响应报文示例

{
    "code": "0",
    "message": "成功",
    "data": {
        "total": 1,
        "results": [
            {
                "id": "3991477",
                "username": "liubang",
                "orgName": "大汉王朝",

            }
        ]
    }
}

接口2

略

编码表

机构查询编码表

库存表错误码

支付错误码

其他

接口文档是用word还是用excel

两种都可以的。
word：
接口数量很多的情况下，照样一个文档下来。
字段列表填写不如excel方便。

excel：
一般一个sheet一个接口，如果接口很多，sheet列表太多，不直观。
对于字段的填写，excel肯定比word方便多了。