YAPI操作文档

king_star_mlt
573 阅读3分钟

YAPI操作文档

什么是YAPI

  • 简单的一句话就是：YAPI是一个API文档管理平台；
  • YAPI的核心作用就是管理API文档，将项目的API同步给项目参与者（开发，测试，产品）；
  • 并方便项目参与者进行接口的调用，测试同步信息

为什么使用YAPI

  • 提升接口文档的维护准确度和效率,通过idea的easyYapi插件自动将controller的接口生成为接口文档
    • 接口的维护管理非常耗时，后端程序员要维护对于他们冗余的文档，前端程序员又因为后端开发提供的文档不准确，导致浪费了大量的时间。
    • 接口的正确性和稳定性很难保证，前端工程师为了处理各种数据异常情况，将会写大量异常处理逻辑。
  • 提升自测和联调效率
    • yapi提供独立的mock功能,接口维护后可以直接进行数据mock提升前端联调效率
    • 可以通过在chrome上安装插件,配置好自己的路径,直接进行接口调用,提升自测效率

如何使用YAPI

  • 根据我们目前的情况,后端我们主要使用YAPI有两个地方:
    • 接口文档生成
    • 自测

接口文档生成

  1. 如何配置本地idea,进行一键快捷生成API文档
    1. 在idea中安装EasyYAPI插件

      安装插件方式: Preferences->plugins->marketplace搜索easyYapi,进行安装

    2. 配置EasyYapi

      由于我们的项目使用@FeignClient去设置的接口路径,而插件默认只会识别Controller的注解,所需要单独配置

      1. 配置识别@FeignClient注解标识的接口
        • 配置方式:
          • 配置位置: Preferences->Other Settings->EasyApi
          • 设置项: 在support选框下勾选feign就能识别@FeignClient注解定义的接口了

      由于默认的识别@FeignClient是无法获取到path参数,导致不能生成正确的API

      1. 配置获取@FeignClient注解标识的path参数
        • 配置方式:
          • 配置位置:Preferences->Other Settings->EasyApi->BuildlnConfig
          • 设置项目: 增加class.prefix.path=@org.springframework.cloud.openfeign.FeignClient#path标识读取@FeignClient的参数作为url前缀

      由于我们项目设置了统一返回参数包装,导致无法正确匹配返回值,所以需要单独配置返回值包裹

      1. 配置统一返回值包裹设置
        • 配置方式:
          • 配置位置:Preferences->Other Settings->EasyApi->BuildlnConfig
          • 设置项目: 增加method.return=groovy: "com.xxx.component.framework.common.model.Result<" + it.returnType() +">"标识给返回值增加外部包装类
        • 注意:由于有部分返回值在AOP中做了过滤,不会包裹,这部分接口需要单独手动在YAPI中维护返回值,相关接口可查看对应的AOP类
      2. 配置要推送yapi的地址
        • 配置方式:
          • 配置位置:Preferences->Other Settings->EasyApi->yapi
          • 设置项目: yapi下的server栏目,将yapi的地址保存到其中
    3. 进行接口文档生成
      1. 创建接口文档项目,在YAPI中创建,或者选择已经创建出来的YAPI文档项目
      2. 在YAPI接口项目中获取到token,获取位置:项目->设置->token配置,可以获取到对应项目接口的token
      3. 在IDEA上打开要生成对应接口文档的项目模块,右键靠近下方的栏目中有Export YAPI选项,点击后会要你输入token,输入token后就会将你本地项目的接口根据不同的@Controller和@FeignClient定义的类或接口的文档生成到YAPI上,会在输出栏目中出现你对应文档的url路径可以点击直接进入

yapi中进行自测

  1. chrome安装插件
  2. 配置本地路径到环境地址中
    • 项目->设置->环境配置,在其中维护自己本地的路径和端口
  3. 维护好参数,点击发送就能请求对应路径的接口了
avatar
文章
阅读
粉丝