接口文档笔记

原创

chushiyunaaa 2023-03-01 09:38:35 博主文章分类：业务 ©著作权

文章标签 字段接口文档码表 文章分类 HarmonyOS 后端开发

©著作权归作者所有：来自51CTO博客作者chushiyunaaa的原创作品，请联系作者获取转载授权，否则将追究法律责任

文章目录

版本变更记录
接口列表

接口1

接口编号+接口名称
请求描述
入参字段
出参字段
请求报文示例
响应报文示例

接口2

编码表

机构查询编码表
库存表错误码
支付错误码

其他

接口文档是用word还是用excel

开发肯定少不了接口文档。

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

版本变更记录

版本变更记录很必要。
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。

出参字段

略

请求报文示例

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

响应报文示例

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

            }
        ]
    }
}