YApi 可视化接口管理平台

对于前后端分离的项目，前后联调，接口平台非常重要

接口的维护管理非常耗时，大概占用了30%开发时间。后端程序员要维护对于他们冗余的文档，前端程序员又因为后端开发提供的文档不准确，导致浪费了大量的时间。

接口的正确性和稳定性很难保证，前端工程师为了处理各种数据异常情况，将会写大量异常处理逻辑。传统的接口自动化测试成本非常高，开发一个接口可能只需要一天，但写接口测试用例，需要花费好几天的时间。

对于前端程序员，在后端功能没有开发完成之前，他们需要接口返回数据 Mock ，以便不影响开发进度。传统的数据 mock 是把模拟数据写到项目代码里，这么做会带来更多新的问题，首先后端程序员定义的接口随着需求、架构涉及随时发生变化的，如果前端程序员完全按照最初的设计定义mock数据，将会和实际做出来的接口有很大的出入。

没有一个标准化的流程统一处理，这个过程是非常分散的，需要配合非常多的工具，效率比较低。

几年前写过《前后端分离API设计指南》,推荐阿里的Rap mock。现在推荐YApi

官方地址：

https://github.com/YMFE/yapi

YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

YApi 特性

• 基于 Json5 和 Mockjs 定义接口返回数据的结构和文档，效率提升多倍

• 扁平化权限设计，即保证了大型企业级项目的管理，又保证了易用性

• 类似 postman 的接口调试

• 自动化测试, 支持对 Response 断言

• MockServer 除支持普通的随机 mock 外，还增加了 Mock 期望功能，根据设置的请求过滤规则，返回期望数据

• 支持 postman, har, swagger 数据导入

• 免费开源，内网部署，信息再也不怕泄露了

YApi 安装

Yapi需要nodejs(npm)和MongoDB

brew install mongodb
brew services start mongodb
npm install -g yapi-cli --registry https://registry.npm.taobao.org
yapi server
npm install pm2 -g  //安装pm2
cd  {项目目录-安装目录}
pm2 start "vendors/server/app.js" --name yapi //pm2管理yapi服务
pm2 info yapi //查看服务信息
pm2 stop yapi //停止服务
pm2 restart yapi //重启服务

或者在浏览器打开 http://0.0.0.0:9090 访问。非本地服务器，请将 0.0.0.0 替换成指定的域名或ip，根据我们实际需求，配置。具体参考《内网搭建yapi接口管理平台 https://zhuanlan.zhihu.com/p/94297858》

手工狗头

在任意一个目录下新建配置文件 yapi-import.json，内容如下：

{
  "type": "swagger",
  "token": "17fba0027f300248b804",
  "file": "swagger.json",
  "merge": "good",
  "server": "http://yapi.local.qunar.com:3000"
}

• type 是数据数据方式，目前官方只支持 swagger

• token 是项目token，在 项目设置 -> token 设置获取

• file 是 swagger 接口文档文件，可使用绝对路径或 url

• merge 导入旧的接口策略，默认使用智能模式，一共有 "normal"(普通模式) , "good"(智能合并), "merge"(完全覆盖) 三种模式

• server 是yapi服务器地址

在新建配置文件的当前目录，执行下面指令就能把数据导入到 yapi 接口管理平台。

yapi import

如果提示找不到 yapi 命令，可尝试执行 yapi-cli,因为部分系统环境不兼容。

YApi大招

• 使用 YApi 管理 API 文档，测试， mock

• 自动更新 Swagger 接口数据到 YApi 平台

• 自动化测试

• export-docx-data 数据导出docx文档

• interface-oauth-token 定时自动获取鉴权token的插件

• import-swagger-customize 导入指定swagger接口

• yapi-to-typescript：根据 YApi 的接口定义生成 TypeScript 的请求函数

• yapi-gen-js-code: 根据 YApi 的接口定义生成 javascript 的请求函数

• Api Generator 接口文档自动生成插件（零入侵）

• mysql服务http工具,可配合做自动化测试

• idea 一键上传接口到yapi插件

• idea 接口上传调试插件 easy-yapi

• 执行 postgres sql 的服务

开车指南：接口文档神器YApi https://segmentfault.com/a/1190000020220258

Spring Boot集成Swagger2并将接口导入YApi

参考：Spring Boot集成Swagger2并将接口导入YApi https://www.jianshu.com/p/88ab66b1538e

在pom.xml文件中添加如下依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>28.1-jre</version>
</dependency>

其中${swagger.version}取值为2.9.2

添加swagger2的配置类

创建Docket，通过其select返回的ApiSelectorBuilder下的apis方法，设置具体的接口文档生成方式，覆盖如下两种：

方式1：只生成特定接口描述，通过在API对应的方法上面添加注解@ApiOperation给API增加说明，通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明

方式2：特定包下所有接口描述，通过指定包名，添加在该包下所有controller层下API说明，统一使用默认的说明方式生成文档；如果需要修改相关描述，可以使用@ApiOperation等注解进行说明

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = { "com.xxx.controller" })//扫描的包路径
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户登录")//接口标题
                .description("用户登录接口")//接口描述
                .version("v1.0")//版本号
                .contact(new Contact("name", "url", "email"))//联系人信息
                .build();
    }
}

Controller类里请求方法加入swagger注解

@ApiOperation(value = "用户登录",tags = {"用户管理"})
    @ApiImplicitParams({ @ApiImplicitParam(name = "userName", value = "用户名", paramType = "body",required=true),
            @ApiImplicitParam(name = "password", value = "密码", paramType = "body",required=true) })
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    public RestResult<String> apiMethod(
            @Valid @RequestBody LoginRequestDTO loginRequestDTO, Errors errors,
            HttpServletRequest request) throws Exception {
          //业务处理
          return null;  
    }

启动Spring Boot服务并访问 http://localhost:8080/swagger-ui.html

swagger注解说明

@ApiOperation:
  value：接口用途（必选）
  notes：备注说明（可选）
  httpMethod：请求方式（可选）
  response：返回参数类型（可选）
  tags：接口分组名（可选）
@ApiImplicitParams:（可选,当描述多个@ApiImplicitParam时候使用）  
  @ApiImplicitParam:（接口入参描述；本身可选，对应子字段也全部可选）  
    name：参数属性名
    value：参数说明
    required：是否必传 true/false
    paramType：请求参数的获取方式
      header --> @RequestHeader
      query -->  @RequestParam
      path -->  @PathVariable
      body  -->  @RequestBody
      form  --> 很少使用
    dataType：参数类型
    defaultValue：默认值
@Api：作用于Conntroller类上
  value：字段说明
  description：描述
  tags：分组
@ApiIgnore: 作用于接口入参参数列表，表示swagger忽略该入参
@ApiModelProperty:作用于入参实体对象的属性上（本身可选，对应子字段也全部可选）
  value：字段描述
  name：属性名字 
  dataType：属性类型 
  required：是否必传
  example：参数样例
  hidden：隐藏
@ApiResponses:(接口返回结果；可选，当描述多个@ApiResponse时候使用)
  @ApiResponse：（可选）
    code：HTTP请求返回码。（必选）
    message：返回信息。（必选）
    response：返回类型，需使用全类名。eg："com.xxx.dto.DemoRequestDTO.class"（可选）

YApi导入Swagger接口

• 通过Swagger的url导入：YAapi 选定项目->数据管理->数据导入，按字段项依次设置即可。

• 通过YApi的Swagger自动同步项（node-schedule 定时任务导入）:YAapi 选定项目->设置->Swagger自动同步，按字段项依次设置即可。

转载本站文章《YApi 可视化接口管理平台》,
请注明出处：https://www.zhoulujun.cn/html/tools/TestTools/Mock/8545.html