前言

接口文档规范了接口信息的书写格式，把接口文档写规范了，前后端对接的时候就能省事很多。
一个项目是有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增加、删除、修改文件到码云

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

此处输入图片的描述

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同理。
使用全局变量的好处是当我们请求的时候，简化了更换地址的操作。如果出现了项目需要换测试环境的情况，也不需要一个一个地去更改接口文档。

接口说明文档使用（后台版）

前言