Yapi 的 使用和介绍 | 8月更文挑战

前言

公司新来了个前端人员，之前的开发规范是一个人单项目开发，独立负责前后端项目，因此就基本没有编写接口文档。

但目前为了开发规范，所以转变开发模式为前后端开发。所以急需一个接口管理服务器，Yapi 的界面足够优美，也不会对代码入侵的特别严重，重要的是可以开源进行内网部署，因此敲定为 Yapi。

一、概述

YAPI是由去哪儿网移动架构组(简称YMFE，一群由FE、iOS和Android工程师共同组成的最具想象力、创造力和影响力的大前端团队)开发的可视化接口管理工具，是一个可本地部署的、打通前后端及QA的接口管理平台。YAPI旨在为开发、产品和测试人员提供更优雅的接口管理服务，可以帮助开发者轻松创建、发布和维护不同项目，不同平台的API。有了YAPI，我们可以很方便的测试、管理和维护多个项目的API接口，不像Swagger那样是随应用生和灭的(且线上环境下大多数须关闭)，YAPI是一个独立的服务平台。

二、安装步骤

环境要求：

• nodejs（7.6+）
• mongodb（2.6+）

本机版本：

[root@localhost my-yapi]# cat /etc/redhat-release
CentOS Linux release 7.9.2009 (Core)
复制代码

2.1 安装nodejs

nodejs 的安装比较简单，可以和参考这篇文章：

centos7 nodejs 的安装

2.2 安装mongodb

可以去官网下载其他版本：

www.mongodb.com/download-ce…

我这里选用的是 mongodb 4.0.10 版本，然后上传到指定目录。

• 1、解压

  [root@localhost package]# tar -xvf mongodb-linux-x86_64-4.0.10.tgz -C /opt/software/
  复制代码

• 2、重命名，配置环境变量

  [root@localhost software]# mv mongodb-linux-x86_64-4.0.10/ mongodb 
  [root@localhost software]# vim /etc/profile
  [root@localhost software]# source /etc/profile
  复制代码

  export MONGODB_HOME=/opt/software/mongodb
  export PATH=$MONGODB_HOME/bin
  复制代码

• 3、创建文件夹

  [root@localhost mongodb]# mkdir -p data/db
  [root@localhost mongodb]# mkdir -p logs
  [root@localhost mongodb]# ls
  bin  data  LICENSE-Community.txt  logs  MPL-2  README  THIRD-PARTY-NOTICES  THIRD-PARTY-NOTICES.gotools
  复制代码

• 4、创建mongodb.conf 配置文件

  dbpath = /opt/software/mongodb/data/db # 数据文件存放目录
  logpath = /opt/software/mongodb/logs/mongodb.log # 日志文件存放目录
  port = 27017 # 端口
  fork = true # 以守护程序的方式启用，即在后台运行
  noauth = true # 不进行安全验证
  # auth=true # 需要认证。如果放开注释，就必须创建MongoDB的账号，使用账号与密码才可远程访问，第一次安装建议注释
  bind_ip=0.0.0.0 # 允许远程访问，或者直接注释，127.0.0.1是只允许本地访问
  复制代码

• 5、启动mongodb，并检查

  [root@localhost mongodb]# bin/mongod -f mongodb.conf 
  Error parsing INI config file: the options configuration file contains an invalid line '访问，第一次安装建议注释'
  try 'bin/mongod --help' for more information
  [root@localhost mongodb]# vim mongodb.conf 
  [root@localhost mongodb]# bin/mongod -f mongodb.conf 
  about to fork child process, waiting until server is ready for connections.
  forked process: 11068
  child process started successfully, parent exiting
  [root@localhost mongodb]# ps -ef|grep mongodb
  root      11068      1  5 14:42 ?        00:00:00 bin/mongod -f mongodb.conf
  root      11270  58533  0 14:43 pts/1    00:00:00 grep --color=auto mongodb
  复制代码

2.3 安装 Yapi-cli

• 1、直接在线安装

  npm install -g yapi-cli --registry https://registry.npm.taobao.org
  yapi server
  复制代码

• 2、访问对应 ip 页面

  

• 3、写上对应信息，部署成功。

  

如果失败了，可能是 yapi 的一个版本bug ，查看这篇文章：www.showdoc.com.cn/p/b9c1a4929…

• 4、进入yapi目录，启动服务器 node vendors/server/app.js

  [root@localhost software]# ls
  java8  mongodb  mysql8  my-yapi  nacos  nginx  node12  redis6
  [root@localhost software]# cd my-yapi/
  [root@localhost my-yapi]# node vendors/server/app.js &
  log: -------------------------------------swaggerSyncUtils constructor-----------------------------------------------
  log: 服务已启动，请打开下面链接访问: 
  http://127.0.0.1:3000/
  log: mongodb load success...
  复制代码

  【注意】：此处 加个 & 是让 yapi 以后台的形式启动，不会关闭窗口后服务停止。

• 5、访问3000 端口，按照它给的账号，密码进行登录

  

2.4 docker 安装

参考：hub.docker.com/r/yapipro/y…

三、Yapi 玩法

3.1 添加分组

3.2 添加项目

3.3 安装浏览器插件

这里可以当成我们的postman 来测试，可以直接进行浏览器访问本地服务。

不过需要安装个 Yapi 跨域插件

测试接口

4.3 配置 token

• windows 下快速发布接口 alt + shift + e、
• mac 下快速发布接口： ctrl + e

4.4 注释demo

4.4.1 controller 层注释写法

​
/**
 * 分类名称
 * 分类备注/描述
 *
 * @module 归属项目
 */
@RestController
@RequestMapping(value = "/pathOfCtrl")
public class MockCtrl {
​
    /**
    * api名称
    * api描述
    * @param param1 参数1的名称或描述
    * @param param2 可以用`@link`来表示当前参数的取值是某个枚举{@link some.enum.or.constant.class}
    * @param param3 当目标枚举字段与当前字段名不一致,额外指定{@link some.enum.or.constant.class#property1}
    * @return 响应描述
    */
    @RequestMapping(value = "/pathOfApi1")
    public Result methodName1(long param1,
                      @RequestParam String param2,
                      @RequestParam(required = false, defaultValue = "defaultValueOfParam3") String param3){
        ...
    }
​
​
    /**
    * 默认使用`application/x-www-form-urlencoded`,
    * 对于`@RequestBody`将使用`application/json`
    * 可以用注解`@Deprecated`来表示api废弃
    * 也可以用注释`@deprecated`
    *
    * @deprecated 改用{@link #methodName3(String)}
    */
    @Deprecated
    @RequestMapping(value = "/pathOfApi2")
    public Result methodName2(@RequestBody MockDtoOrVo jsonModel){
        ...
    }
​
    /**
    * 所有注释或者参数描述中都可以使用`@link`来引用另一个API
    * 例如:
    * 请先访问{@link #methodName4(String)}
​
    * 也可以使用`@see`来引用另一个API
    *
    * @param param1 参数1的名称或描述 可以从{@link #methodName5(String)}中获得
    * @see #methodName6(String)
    * @deprecated 改用{@link #methodName7(String)}
    */
    @Deprecated
    @RequestMapping(value = "/pathOfApi3")
    public Result methodName3(long param1){
        ...
    }
​
    ...
}
复制代码

4.4.2 实体类注释写法

public class MockDtoOrVo {
​
    /**
     * 字段注释
     */
    private Long field1;
​
    private Double field2;//注释也可以写在这
​
    /**
     * 使用@see来说明当前字段的取值是某个枚举
     * @see some.enum.or.constant.class
     */
    private int field3;
​
    /**
     * 当目标枚举字段与当前字段名不一致,额外指定
     * @see some.enum.or.constant.class#property1
     */
    private int field4;
​
    /**
     * 可以用注解`@Deprecated`来表示字段被废弃
     * 也可以用注释`@deprecated`
     * @deprecated It's a secret
     */
    @Deprecated
    private int field5;
​
    /**
     * 如果使用javax.validation的话
     * 可以使用@NotBlank/@NotNull表示字段必须
     */
    @NotBlank
    @NotNull
    private String field6;
​
    ...
}
复制代码

4.5 常用配置规则

4.5.1 module

• 用于API分组
• 当无配置生效时, 默认使用当前模块/项目名
• 导出postman时,将为每个module创建一个文件夹
• 导出yapi时,每个module对应yapi中的一个项目

demo:

/**
* Mock Apis
*
* @module mock
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
}
复制代码

4.5.2 ignore

用于忽略方法 或忽略 类。

demo:

/**
* Mock Apis
*
* @ignore
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
}
复制代码

4.5.3 json.rule.field.name

• 用于设置 输出 或输入的字段名不一样的情况

demo：

public class TestJsonFieldBean {
    @JsonProperty("a")
    private Long propertyA;
​
    @SerializedName("b")
    private Long propertyB;
}
复制代码

导出结果为：

4.5.4 json.rule.field.ignore

忽略字段

demo：

public class TestJsonIgnoreBean {
​
    @Expose(serialize = true)
    private Long shouldNotIgnoreForGson;
​
    @Expose(serialize = false)
    private Long shouldIgnoreForGson;
​
    @JsonIgnore(false)
    private Long shouldNotIgnoreForJackson;
​
    @JsonIgnore
    private Long shouldIgnoreForJackson;
}
复制代码

导出结果：