接口文档笔记

朱雀 2022-10-22 06:26 374阅读 0赞

### 文章目录 ###

*   *  版本变更记录
     *  接口列表
     *   *  接口1
         *   *  接口编号+接口名称
             *  请求描述
             *  入参字段
             *  出参字段
             *  请求报文示例
             *  响应报文示例
         *  接口2
     *  编码表
     *   *  机构查询编码表
         *  库存表错误码
         *  支付错误码
     *  其他
     *   *  接口文档是用word还是用excel

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

## 版本变更记录 ##

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

例如：

## 接口列表 ##

### 接口1 ###

#### 接口编号+接口名称 ####

例如 3.3.1 用户查询接口

#### 请求描述 ####

<table> 
 <thead> 
  <tr> 
   <th>–</th> 
   <th align="left">–</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>请求地址</td> 
   <td align="left">http://prd-domain.net/crm/api/findUser<br>生产环境<br>http://sit-domain.net/crm/api/findUser<br>测试环境</td> 
  </tr> 
  <tr> 
   <td>请求方式</td> 
   <td align="left">HTTP POST</td> 
  </tr> 
  <tr> 
   <td>入参类型</td> 
   <td align="left">JSON</td> 
  </tr> 
  <tr> 
   <td>出参类型</td> 
   <td align="left">JSON</td> 
  </tr> 
 </tbody> 
</table>

#### 入参字段 ####

<table> 
 <thead> 
  <tr> 
   <th align="left">序号</th> 
   <th align="left">输入项</th> 
   <th align="left">类型</th> 
   <th align="left">是否必填</th> 
   <th align="left">字段含义</th> 
   <th align="left">备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">1</td> 
   <td align="left">username</td> 
   <td align="left">VARCHAR2(255)</td> 
   <td align="left">是</td> 
   <td align="left">用户名</td> 
   <td align="left"></td> 
  </tr> 
  <tr> 
   <td align="left">1</td> 
   <td align="left">orgName</td> 
   <td align="left">VARCHAR2(255)</td> 
   <td align="left">否</td> 
   <td align="left">用户名</td> 
   <td align="left"></td> 
  </tr> 
 </tbody> 
</table>

字段类型这里可填的方式有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": "大汉王朝",
    
                }
            ]
        }
    }

### 接口2 ###

略

## 编码表 ##

### 机构查询编码表 ###

### 库存表错误码 ###

### 支付错误码 ###

## 其他 ##

### 接口文档是用word还是用excel ###

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

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