YApi 简单介绍

前后端分离的接口文档管理

在前后端分离之前，我们开发一个 web 服务基本上都是 MVC 模式。当浏览器给服务端发送请求时，会先经过路由映射找到对应的视图函数，然后视图函数执行逻辑（比如从缓存、数据库里面读取数据），最后肯定要返回一个 html 文件。因此还要读取 html 模板，然后进行渲染，最终返回给浏览器。

但是这样就有一个问题，那就是 html 模板由谁来写呢？因为 html 模板和纯 html 还是不太一样的，html 模板里面是包含一些后端逻辑的。因此一般的做法时，前端工程师写好一个静态的 html 文件，然后后端工程师再对这个静态文件进行修改。

但是很明显，这样下来成本会很高，因为前端工程师对 html 文件做了任何一点点改动，都要通知后端工程师，否则前端做的任何修改都是无效的。

但是现在前后端分离之后，前端工程师和后端工程师可以专注于各自的职责了。html、css、js 等文件全部由前端来负责编写，浏览器也不再向服务端发送请求了，而是前端发请求。但是前端没有数据啊，是的，接下来就由前端服务向后端服务发请求，所以此时后端只需要返回纯数据就可以了，前端在拿到数据之后进行渲染就可以了。

所以此时就实现了前端和后端的解耦，前端专注于页面展示，后端专注于业务逻辑，只需要给前段返回纯数据即可，而返回的数据基本上都是 json 格式（也可以是其它格式，比如 protobuf）。但是问题来了，之前数据的渲染是由后端来做的，只需要返回渲染之后的 html 文件即可，但现在这个逻辑由前端来做了。所以这就多了两个问题：

1. 后端必须告诉前端返回的 json 数据都有哪些字段、以及每一个字段的含义
2. 前端在给后端发送请求的时候 url 里面的参数的含义

因此多了一层数据的解释，而解决办法一般都是通过文档，后端定义好 url 的格式以及每个组成部分的含义，以及返回的 json 都有哪些字段等等。

虽然通过接口文档是可以解决的，但多多少少还是不太方便，能不能提供一个可以在线测试的页面呢？可能有人想到 Swagger，但那是针对后端开发人员测试某个接口是否正常工作；而前端人员需要的是这个接口能不能正常返回数据，以及在拿到这些数据之后能不能正常渲染在页面上，因为最终用户看的都是前端页面。

另外，即便接口文档上写了某个接口，url 参数、返回值的含义都写很清楚，但是后端没有开发好，这个时候前端也无法做测试的。而一般前端都会根据接口文档自己来一套 mock 系统，会生成一些假的测试数据，并且后端没有提供 mock 系统，都是前端本地 mock。但是一旦后端改了某个接口，那么接口文档、前端的 mock 系统都要手动同步，而且接口文档很多都是采用 Markdown 手动编写的。

所以我们的主角来了，它叫 YApi，我们只需要写好接口、定义好返回值格式即可。这样后端人员在测试的时候，可以通过 YApi 直接发请求，并且它还能验证返回的数据是否合法，因为我们定义了返回值格式。不仅如此，前端也可以使用 YApi，如果接口没有开发好，那么它会自动生成 mock 数据，这样就方便很多了。而且由于前端和后端使用的都是同一套接口测试，那么后端做的任何修改，前端都可以感知到。最方便的是，YApi 还可以生成测试集，我们可以同时测试一批接口，然后一键点击，就可以告诉你哪些接口有问题。

YApi 的安装与配置

YApi 的安装实际上还是比较麻烦的，最方便的做法是采用 Docker 安装，下面我们来看一下安装过程，也可以直接去 https://github.com/fjc0k/docker-YApi 查看。

1. git clone https://github.com/fjc0k/docker-YApi.git

2. cd docker-YApi

3. docker-compose up 启动服务, 但这是前台启动, 可以加上 -d 参数后台启动

然后我们浏览器访问 ip:40001 即可查看相关页面

但是我们还看到了登陆/注册按钮，如果你点击的话会让你选择是登陆还是注册。登陆的话需要邮箱和密码，注册的话会提示管理员已禁止注册，那么这个时候怎么办呢？所以我们需要修改 docker-YApi 下面的 docker-compose.yml 文件，我们把它贴出来看看长什么样子吧。

version: '3'

services:
  yapi-web:
    image: jayfong/yapi:latest  # 拉取的镜像
    container_name: yapi-web    # 启动容器时采用的名字
    ports:
      - 40001:3000              # 对外暴露 40001 端口、映射到容器内部的 3000 端口
    environment:
      - YAPI_ADMIN_ACCOUNT=admin@docker.yapi  # 管理员邮箱
      - YAPI_ADMIN_PASSWORD=adm1n             # 管理员密码
      - YAPI_CLOSE_REGISTER=true              # 是否关闭注册功能，如果你希望别人注册的话就设置为 false
                                              # 但即使设置为 true，我们也可以后台手动添加
                                              
      - YAPI_DB_SERVERNAME=yapi-mongo         # 依赖 MongoDB，表示 MongoDB 的服务地址
      - YAPI_DB_PORT=27017                    # MongoDB 的服务端口
      - YAPI_DB_DATABASE=yapi                 # 使用的 MongoDB 数据库
      - YAPI_MAIL_ENABLE=false                # 是否启动右键配置，如果启动的话还需要设置其它变量，比如：发送人邮箱等等
                                              # 具体可以前往 GitHub 查看
                                              
      - YAPI_LDAP_LOGIN_ENABLE=false          # 是否开启登陆配置
      - YAPI_PLUGINS=[]                       # 插件配置
    depends_on:
      - yapi-mongo                            # 依赖的镜像
    links:
      - yapi-mongo                            # 启动时关联的容器
    restart: unless-stopped
  yapi-mongo:
    image: mongo:latest
    container_name: yapi-mongo
    volumes:
      - ./data/db:/data/db                    # 挂载卷
    expose:
      - 27017                                 # MongoDB 暴露的端口
    restart: unless-stopped

如果你修改了配置，那么一定要重启：docker-compose restart yapi-web，另外我这里只是介绍了一些基本用法，更详细的内容可以去上面说的 GitHub 地址查看。

然后我们登陆进去：