idea同步yapi插件的详细步骤

更新时间：2024年04月28日 11:01:19 作者：七夜琉璃

yapi是一个很好的接口文档维护工具,其swagger功能,可将接口信息同步到yapi平台上,这篇文章主要介绍了idea同步yapi插件,需要的朋友可以参考下

1、前言

yapi是一个很好的接口文档维护工具，其swagger功能，可将接口信息同步到yapi平台上，但是swagger的编写，大量入侵代码，也加大了开发工作量，目前调研了idea集成yapi同步工具，无需嵌入式编写入侵代码，根据javadoc备注即可将接口信息同步到yapi同台上

2、idea同步yapi平台工具

Idea支持将接口文档同步到yapi目前找到三个，easyapi、YapiUpload、idea yapi

easyapi：同步接口信息到postman以及yapi平台上，但是同步yapi的不支持多模块同步；
YapiUpload：同步yapi的配置需要写配置文件，不利于维护；
idea yapi：是基于YapiUpload的二次开发，将原有xml配置方式改为 Setting 中配置，并配置持久化，将原本上传的数据类型做了优化，上传后数据类型为js的数据类型。

综上优缺点，可采用idea yapi，如果有特殊需求可安装easyapi同步到postman进行接口调试

3、idea-yapi安装步骤

3.1、安装idea-yapi

在idea-Preferences-Plugins中搜索idea-yapi，安装，并重启idea

3.2、配置idea-yapi

在idea-Preferences-Other Setting中找到YapiSetting
配置说明如下：

如果你是项目只是同步dubbo/api，采用如下配置

{
  "isSingle": true,
  "singleConfig": {
    "projectToken": "yapi平台的项目token地址",
    "projectId": "yapi平台的项目id",
    "yApiUrl": "yapi平台平台地址",
    "menu": "同步到的接口的目录",
    "projectType": "你的接口类型或者dubbo"
  },
  "multipleConfig": {
    "api": {
      "projectToken": "",
      "projectId": "",
      "yApiUrl": "",
      "menu": "",
      "projectType": ""
    },
    "api": {
      "projectToken": "",
      "projectId": "",
      "yApiUrl": "",
      "menu": "",
      "projectType": ""
    }
  }
}

如果你是项目即同步dubbo又有api，采用如下配置

{
  "isSingle": false,
  "singleConfig": {
    "projectToken": "",
    "projectId": "",
    "yApiUrl": "",
    "menu": "",
    "projectType": ""
  },
  "multipleConfig": {
    "接口所在包名称: {
       "projectToken": "yapi平台的项目token地址",
       "projectId": "yapi平台的项目id",
       "yApiUrl": "yapi平台平台地址",
       "menu": "api接口文档",
        "projectType": "api"
    },
    "dubbo所在包名称": {
      "projectToken": "yapi平台的项目token地址",
       "projectId": "yapi平台的项目id",
       "yApiUrl": "yapi平台平台地址",
       "menu": "dubbo文档",
        "projectType": "dubbo"
    }
  }
}

备注：查找token以及项目id的目录

3.3、同步接口或者dubbo

找到对应的接口所在的方法入口或者dubbbo的定义方法，即可
比如：同步下面的接口

效果如下：

4、idea-yapi支持规则配置以及实例

4.1、规则配置

1:插件如何生成属性备注 ,通过获得字段备注中的注释

/** 
* 年龄
*/
private Integer age;

2:插件如何生成接口名称，通过接口上的注释，或者引用上的注释

/**
     * 添加或更新课程数据
     *
     * @param courseOpt
     * @return {@link CommonRes}
     */
    @RequestMapping(value = "/test", method = RequestMethod.POST)
    public Course addOrUpdateCourse(@RequestBody CourseParam courseParam){
    }
    /**
     * @description: 添加或更新课程数据  (@Description 也可）
     * @param: [CourseParam]
     * @return: Course
     * @date: 2018/3/15
     */
     @RequestMapping(value = "/test", method = RequestMethod.POST)
     public Course addOrUpdateCourse(@RequestBody CourseParam courseParam){
    }
     @RequestMapping(value = ICourse.ADD_OR_UPDATA_COURSE, method = RequestMethod.POST)
     public Course addOrUpdateCourse(@RequestBody CourseParam courseParam){
     }
     public interface  ICourse{
       /**
        * @description: 添加或更新课程数据  (@Description 也可）
        * @param: [CourseParam]
       */
       ADD_OR_UPDATA_COURSE="test";
     }

3:@link 参数定义展示在字段备注中
第一种@link 方式

/** 
* 状态 {@link com.xxx.constant.StatusConstant}
*/
private Integer status;

第二种@link 方式

import com.xxx.constant.StatusConstant;
/** 
* 状态 {@link StatusConstant}
*/
private Integer status;

不支持方式

import com.xxx.constant.*;
/** 
* 状态 {@link StatusConstant}
*/
private Integer status;

4:实现自定义分类
通过在方法或类注释中加 @menu 注释实现，优先级方法>类>package 下面或者上面的@menu,如果没有自定义默认为tool-tmp,支持多级分类（多级分类只能是crazy 分支的yapi)

package com.project.demo;
/** 
 * @menu 这里填写类分类名称
 */
import com......
/** 
 *@description: 用户控制器
 *@menu 这里填写类分类名称
 */   
@RestController
public class UserController {
    /**
     * @description: 新增用户
     * @param: [User]
     * @menu: 这里填写方法级别分类名称（比如 多级目录/menu/menu1/menu2)
     * @return: Response<UserDTO>
     * @date: 2018/3/15
     */
     @RequestMapping(value = "/addUser", method = RequestMethod.POST)
     public Response<UserDTO> addUser(@RequestBody User user){
    }
}

5:支持注解

  String RequestMapping="org.springframework.web.bind.annotation.RequestMapping";
    String GetMapping="org.springframework.web.bind.annotation.GetMapping";
    String PostMapping="org.springframework.web.bind.annotation.PostMapping";
    String PutMapping="org.springframework.web.bind.annotation.PutMapping";
    String DeleteMapping="org.springframework.web.bind.annotation.PutMapping.DeleteMapping";
    String PatchMapping="org.springframework.web.bind.annotation.PutMapping.PatchMapping";
    String RequestBody="org.springframework.web.bind.annotation.RequestBody";
    String RequestParam="org.springframework.web.bind.annotation.RequestParam";
    String RequestHeader="org.springframework.web.bind.annotation.RequestHeader";
    String RequestAttribute="org.springframework.web.bind.annotation.RequestAttribute";
    String PathVariable="org.springframework.web.bind.annotation.PathVariable";
    String NotNull="javax.validation.constraints.NotNull";
    String NotEmpty="javax.validation.constraints.NotEmpty";
    String NotBlank="javax.validation.constraints.NotBlank";

支持Request Param 注解
生成的 uid 和bid 备注为用户id(Integer),baby id(Integer) 如果没有备注，则只有(Integer)

   /**
     * 测试RequestHeader desc 规范的多个
     * @param uid 用户id
     * @param bid baby id
     * @param request
     * @param response
     */
    @RequestMapping(value = "/testRequestDesc4")
    public void testRequestDesc4(@RequestHeader(name = "uid")Integer uid, @RequestParam(name = "bid")Integer bid, HttpServletRequest request, HttpServletResponse response){
    }

支持@status注解
支持已发布(done),设计中(design),开发中(undone),已提测(testing),已过时(deprecated),暂停开发(stoping),支持中英文（crazy 分支)，新增接口默认开发中,更新时如果没有写status情况下默认使用当前状态

   /**
     * 测试RequestHeader desc 规范的多个
     * @param uid 用户id
     * @status 开发中 (或者 undone)
     * @param request
     * @param response
     */
    @RequestMapping(value = "/testRequestDesc4")
    public void testRequestDesc4(@RequestHeader(name = "uid")Integer uid, @RequestParam(name = "bid")Integer bid, HttpServletRequest request, HttpServletResponse response){
    }

6:项目中通过fitler或拦截器或注解等实现全局统一响应对象返回如何处理
在misc.xml 中配置 returnClass ，值为全局统一响应对象全路径。比如下面代码如果配置了returnClass 为GlobalResponse ,那么他生成的yapi 响应对象为，GlobalResponse

   /**
     * 测试RequestHeader desc 规范的多个
     * @param uid 用户id
     * @status 开发中 (或者 undone)
     * @param request
     * @param response
     */
    @RequestMapping(value = "/testRequestDesc4")
    public Integer testRequestDesc4(@RequestHeader(name = "uid")Integer uid, @RequestParam(name = "bid")Integer bid, HttpServletRequest request, HttpServletResponse response){
    }
public class GlobalResponse<T> {
    private String status;
    private String code;
    private T data;
  ......
}

7:swagger 支持
目前1.7.7以上支持以下注解

  String API_OPERATION = "io.swagger.annotations.ApiOperation";
  String API_MODEL_PROPERTY = "io.swagger.annotations.ApiModelProperty";
  String API_PARAM = "io.swagger.annotations.ApiParam";

4.2、实例

4.2.1、get方式

        /**
         * get方式
         *
         * @param param1 参数1的名称或描述
         * @param param2 参数2的名称或描述
         * @param param3 参数3的名称或描述
         * @return 响应描述
         * @author 苏叶
         * @date 2019-12-29 17:24
         */
        @RequestMapping(value = "/pathOfApi1", method = RequestMethod.GET)
        public Response<GuideResult> methodName1(@RequestParam String param1,
                                                 @RequestParam String param2,
                                                 @RequestParam(required = false, defaultValue = "android") String param3) {
            return new Response<GuideResult>();
        }

效果

4.2.2、Post方式

       /**
         * post方式
         *
         * @param jsonModel 入参数
         * @return 通用返回
         * @author 苏叶
         * @date 2019-12-29 17:20
         */
        @Deprecated
        @RequestMapping(value = "/pathOfApi2", method = RequestMethod.POST)
        public Response methodName2(@RequestBody MockDtoOrVo jsonModel) {
            return new Response();
        }

MockDtoOrVo 入参

/**
 * moke说明
 *
 * @author 苏叶
 * @version 1.0
 * @date 2019-12-29 16:58
 */
@Data
@ToString
public class MockDtoOrVo {
    /**
     * 字段注释
     */
    private Long field1;
    /**
     * 字段注释
     */
    private Double field2;
    /**
     * 某个枚举
     * {@link com.kaishustory.userx.common.constant.ClientForm}
     */
    private int field3;
    /**
     * 当目标枚举字段与当前字段名不一致,额外指定
     *
     * @see com.kaishustory.userx.common.constant.ClientForm#ANDROID
     */
    private int field4;
    /**
     * 可以用注解`@Deprecated`来表示字段被废弃
     * 也可以用注释`@deprecated`
     *
     * @deprecated It's a secret
     */
    @Deprecated
    private int field5;
    /**
     * 如果使用javax.validation的话
     * 可以使用@NotBlank/@NotNull表示字段必须
     */
    @NotBlank
    @NotNull
    private String field6;
}

效果

5、EasyApi安装步骤

5.1、安装EasyApi

在idea-Preferences-Plugins中搜索easyapi，安装，并重启idea

5.2、创建postmantoken获取token

5.3、配置easyapi导出postman

5.4、项目配置

.easy.api.yml

实例在moudle下面配置如下

在对应的controller文件右键-genernate - export postman，即可

生成对应目录的请求配置

具体的方法注释：
https://github.com/diwand/YapiIdeaUploadPlugin/wiki/%E5%BF%AB%E9%80%9F%E4%BD%BF%E7%94%A8

到此这篇关于idea同步yapi插件的文章就介绍到这了,更多相关idea同步yapi插件内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

Java深入探究关键字abstract的使用
如果一个方法使用 abstract 来修饰，则说明该方法是抽象方法，抽象方法只有声明没有实现。需要注意的是 abstract 关键字只能用于普通方法，不能用于 static 方法或者构造方法中
2022-05-05
Java transient关键字原理解析
这篇文章主要介绍了Java transient关键字原理解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-01-01
Springboot在有参构造方法类中使用@Value注解取值
这篇文章主要介绍了Springboot在有参构造方法类中使用@Value注解取值,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-06-06
java连接zookeeper的实现示例
ZooKeeper官方提供了Java API,可以通过Java代码来连接zookeeper服务进行操作,本文就来介绍一下java连接zookeeper的实现示例,具有一定的参考价值,感兴趣的可以了解一下
2023-11-11
详解springmvc如何处理接受http请求
这篇文章主要给大家介绍了springmvc如何处理接受http请求,文中通过代码示例给大家讲解的非常详细,对大家的学习或工作有一定的帮助,需要的朋友可以参考下
2024-02-02
Spring注解@Qualifier的使用&&与@Primary注解的不同
今天带你了解一下Spring框架中的@Qualifier 注解,它解决了哪些问题,以及如何使用它,我们还将了解它与 @Primary 注解的不同之处,感兴趣的朋友跟随小编一起看看吧
2023-10-10
Java根据正整数的位数并逆序打印出各位数字
给一个不多于5位的正整数，要求：一、求它是几位数，二、逆序打印出各位数字,需要的朋友可以参考下
2017-02-02
Springboot整合camunda+mysql的集成流程分析
本文介绍基于mysql数据库，如何实现camunda与springboot的集成，如何实现基于springboot运行camunda开源流程引擎，本文分步骤图文相结合给大家介绍的非常详细，需要的朋友参考下吧
2021-06-06
Java如何判断一个空对象的常见方法
在Java中判断对象是否为空是一项重要的编程技巧,可以有效防止空指针异常的发生,下面这篇文章主要给大家介绍了关于利用Java如何判断一个空对象的相关资料,需要的朋友可以参考下
2024-01-01
Java设计模式之责任链模式的概念、实现以及netty中的责任链模式
这篇文章主要给大家介绍了关于设计模式之责任链模式的概念、实现以及netty中的责任链模式的相关资料，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2020-12-12