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

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 页面

    image-20210719144927550

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

    image-20210719145231433

如果失败了,可能是 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 端口,按照它给的账号,密码进行登录

    image-20210719145844363

2.4 docker 安装

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

三、Yapi 玩法

3.1 添加分组

image-20210719150409013

3.2 添加项目

image-20210719150509211

3.3 安装浏览器插件

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

image-20210719161132466

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

image-20210719161438844

测试接口

image-20210721104629710

image-20210719151209803

4.3 配置 token

image-20210719151345534

  • 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;
}
复制代码

导出结果为:

名称类型是否必须默认值备注其他信息
ainteger非必须mock: @natural(0,10000)
binteger非必须mock: @natural(0,10000)
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;
}
复制代码

导出结果:

名称类型是否必须默认值备注其他信息
shouldNotIgnoreForGsoninteger非必须mock: @natural(0,10000)
shouldNotIgnoreForJacksoninteger非必须mock: @natural(0,10000)
分类:
后端
标签: