接口文档
什么是接口文档?
在项目开发中,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. 接口定义
2. 附录
接口 说明
接口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.1 返回码详细定义
返回码 描述
0 请求成功
1 缺少用户名或密码
2 用户名或密码错误