接口文档

什么是接口文档？

　　在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

　　

为什么要使用接口文档？

　　1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发。
　　2、项目维护中或者项目人员更迭，方便后期人员查看、维护。

 

接口文档的核心是什么？

　　接口核心分为四个部分： 请求方法、 uri、请求参数、返回参数。

• 请求方法： 即请求的方法是什么。常用的请求方法有get、post、delete、put。
• uri： 即客户端需要向哪里进行请求。
• 请求参数和返回参数:都分为5列：字段、说明、类型、备注、是否必填
  字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；备注是一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。返回参数结构有几种情况：1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：code和message两个参数；2、如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；3、如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。

 

接口文档举例

　  我们可以按照下面的这种方式来写文档：

• 文档信息
• 文档名称
• 文档管理编号
• 保密级别
• 文档类型
• 扩散范围
• 使用范围
• 版权所有
• 版本变更记录
• 版本-说明-时间-修改人  如1.0-新建文档-2017年5月11日-朱振伟

---

（说明： 上面我们可以按照这种方式定义一些基本信息，加下来就可以定义具体的接口了， 虽然可以直接定义接口，但是这样更有条理，通俗，易懂。）

目录

1. 接口定义
接口 说明
接口1 接口1说明
1.1接口1定义
接口调用请求说明
http请求方式：POST/FORM
编码方式：UTF-8
https://xxxxx
示例（使用curl命令）：
curl -F resultFile=@/tmp/xxx -k https://xxx
参数说明
参数 说明
参数1 参数1说明
返回值
正确情况下的返回：
<?xml version="1.0" encoding="UTF-8"?>
<Result>
<Code>0</Code> // 返回码，返回码详细定义参见附录
<Message><![CDATA[请求成功]]></Message> // 返回码描述信息
<Data>
......
</Data>
</Result>
错误情况下的返回：
<?xml version="1.0" encoding="UTF-8"?>
<Result>
<Code>1</Code> // 返回码，返回码详细定义参见附录
<Message><![CDATA[缺少用户名或密码]]></Message> // 返回码描述信息
</Result>

2. 附录
2.1 返回码详细定义
返回码 描述
0 请求成功
1 缺少用户名或密码
2 用户名或密码错误