前言

接口文档规范了接口信息的书写格式,把接口文档写规范了,前后端对接的时候就能省事很多。
一个项目是有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"}


    
    ipaddr是配置的运行环境,具体详情在下方的定义全局变量有说。
    a、b、c均为参数,xxxxxx为该参数的值。
     

3.返回参数说明(下面的绿字)

返回参数          描述

    A        返回参数A的描述

    B        返回参数B的描述

VSCode使用

一、使用VS Code增加、删除、修改文件到码云

  1. 增加、删除、修改文件。
  2. 打开‘源代码管理’,点击‘+’,把更改提交到暂存区
    (当鼠标移至更改当中,会出现'+'按钮)

此处输入图片的描述

3.点击‘’提交暂存区的文件,填写提交信息后按Enter。

(此时暂存区的修改都被提交,列表为空)

再点击界面下方的图标进行上传 (平时更新下拉也可以点击这个图标)

此处输入图片的描述

4.更新完成


二、定义全局变量

示例当中的{{ipaddr}}为封装好的全局变量,ipaddr只是我们自己给的一个名字,没有什么特殊含义。
打开.vscode/settings.json,文件配置全局变量代码如下:


{
    "rest-client.environmentVariables": {
        "$shared": {
            "version": "v1"
        },
        "local": {
            "ipaddr": "http://127.0.0.1/parchment",
            "token": "test token"
        },
        "net": {
            "ipaddr": " ",
            "token": "test token"
        }
    }
}

在local环境中,我们给ipaddr的赋值为http://127.0.0.1/parchment,net同理。
使用全局变量的好处是当我们请求的时候,简化了更换地址的操作。如果出现了项目需要换测试环境的情况,也不需要一个一个地去更改接口文档。

标签: none

添加新评论