接口文档使用说明(前端版)
前言
前端每实现一个接口,需要清楚知道要传的参数和返回的信息。
接口文档规范了接口信息的书写格式,前端人员只需要看懂了下面的规范便能轻松地了解所有接口的信息。
一个项目是有n个接口的,为了方便管理、查看这n个接口文档,我们使用的是VS Code。
接口文档的规范
为了方便大家快速看懂,我们用一个简单例子来解释。(查看用户预约成功后的信息)
主要分为以下三个部分:
1.请求参数说明(上面的绿字)
请求方式: (GET/POST)
参数 是否必填 参数格式 参数作用
a (必填/非必填) (String/int) xxxxx
b (必填/非必填) (String/int) xxxxx
c (必填/非必填) (String/int) xxxxx
2.请求接口成功的示例(中间的白字)
GET/POST请求 GET/POST {{ipaddr}}/XXXXXXX
?json={"a":"xxxxxx","b":"xxxxxx","c":"xxxxxx"}
Send Request是一个点击按钮,用于发送请求,具体解释在后面的VSCode使用当中。
ipaddr是配置的请求地址。如有兴趣了解,可以看接口文档使用说明(后端版)。
a、b、c均为参数,xxxxxx为该参数的值。
3.返回参数说明(下面的绿字)
返回参数 描述
A 返回参数A的描述
B 返回参数B的描述
VSCode使用
一、软件准备
- VS Code
- Git for windows (ios不用下载)
二、使用GitBash(Git for windows)从码云下拉接口文档
- 打开Git Bash
按顺序输入以下命令
- 选择保存路径
cd {ProjectPath}
(例
cd F:
,即为保存在F盘)- 克隆项目
git clone {GitURL}
(每个项目的URL不一样,根据实际情况输入。例:git clone https://gitee.com/D_e_n_g/parchment-api_images.git)
第一次使用GitBash会出现提示框要求输入码云帐号密码,输入正确后获得对应的下拉权限。
- 选择保存路径
- 下拉文档完成
三、使用VS Code查看接口文档、测试接口
- 从导航栏的文件中选择打开文件夹,注意!是文件夹!
- 打开扩展,安装REST Client并启动 。
该组件的作用是使接口文档的示例上方出现send Request,并对示例链接进行请求。
3.打开任意接口文档,选择环境变量
在软件的右下方点击No Environment,上方弹框选择net。每次点击SendRequest是在测试环境进行接口请求。local是后端人员进行开发时所用。
No Environment没有显示的问题:
1.只有后缀名为.http的文件才会有这一选项
2.REST Client组件没有启动,进入扩展选择启动
4.打开接口文档,发送请求
点击链接上的Send Request,右方会出现请求返回结果。
四、VSCode同步代码
- 打开‘源代码管理’ ,左侧导航栏的第三个
- 单击右上角的‘···’→点击‘同步’
- 同步代码完成
111
22