idea同步y(tǒng)api插件的詳細步驟

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

yapi是一個很好的接口文檔維護工具,其swagger功能,可將接口信息同步到y(tǒng)api平臺上,這篇文章主要介紹了idea同步y(tǒng)api插件,需要的朋友可以參考下

1、前言

yapi是一個很好的接口文檔維護工具，其swagger功能，可將接口信息同步到y(tǒng)api平臺上，但是swagger的編寫，大量入侵代碼，也加大了開發(fā)工作量，目前調(diào)研了idea集成yapi同步工具，無需嵌入式編寫入侵代碼，根據(jù)javadoc備注即可將接口信息同步到y(tǒng)api同臺上

2、idea同步y(tǒng)api平臺工具

Idea支持將接口文檔同步到y(tǒng)api目前找到三個，easyapi、YapiUpload、idea yapi

easyapi：同步接口信息到postman以及yapi平臺上，但是同步y(tǒng)api的不支持多模塊同步；
YapiUpload：同步y(tǒng)api的配置需要寫配置文件，不利于維護；
idea yapi：是基于YapiUpload的二次開發(fā)，將原有xml配置方式改為 Setting 中配置，并配置持久化，將原本上傳的數(shù)據(jù)類型做了優(yōu)化，上傳后數(shù)據(jù)類型為js的數(shù)據(jù)類型。

綜上優(yōu)缺點，可采用idea yapi，如果有特殊需求可安裝easyapi同步到postman進行接口調(diào)試

3、idea-yapi安裝步驟

3.1、安裝idea-yapi

在idea-Preferences-Plugins中搜索idea-yapi，安裝，并重啟idea

3.2、配置idea-yapi

在idea-Preferences-Other Setting中找到Y(jié)apiSetting
配置說明如下：

如果你是項目只是同步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

找到對應(yīng)的接口所在的方法入口或者dubbbo的定義方法，即可
比如：同步下面的接口

效果如下：

4、idea-yapi支持規(guī)則配置以及實例

4.1、規(guī)則配置

1:插件如何生成屬性備注 ,通過獲得字段備注中的注釋

/** 
* 年齡
*/
private Integer age;

2:插件如何生成接口名稱，通過接口上的注釋，或者引用上的注釋

/**
     * 添加或更新課程數(shù)據(jù)
     *
     * @param courseOpt
     * @return {@link CommonRes}
     */
    @RequestMapping(value = "/test", method = RequestMethod.POST)
    public Course addOrUpdateCourse(@RequestBody CourseParam courseParam){
    }
    /**
     * @description: 添加或更新課程數(shù)據(jù)  (@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: 添加或更新課程數(shù)據(jù)  (@Description 也可）
        * @param: [CourseParam]
       */
       ADD_OR_UPDATA_COURSE="test";
     }

3:@link 參數(shù)定義展示在字段備注中
第一種@link 方式

/** 
* 狀態(tài) {@link com.xxx.constant.StatusConstant}
*/
private Integer status;

第二種@link 方式

import com.xxx.constant.StatusConstant;
/** 
* 狀態(tài) {@link StatusConstant}
*/
private Integer status;

不支持方式

import com.xxx.constant.*;
/** 
* 狀態(tài) {@link StatusConstant}
*/
private Integer status;

4:實現(xiàn)自定義分類
通過在方法或類注釋中加 @menu 注釋實現(xiàn)，優(yōu)先級方法>類>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 規(guī)范的多個
     * @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注解
支持已發(fā)布(done),設(shè)計中(design),開發(fā)中(undone),已提測(testing),已過時(deprecated),暫停開發(fā)(stoping),支持中英文（crazy 分支)，新增接口默認開發(fā)中,更新時如果沒有寫status情況下默認使用當前狀態(tài)

   /**
     * 測試RequestHeader desc 規(guī)范的多個
     * @param uid 用戶id
     * @status 開發(fā)中 (或者 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或攔截器或注解等實現(xiàn)全局統(tǒng)一響應(yīng)對象返回如何處理
在misc.xml 中配置 returnClass ，值為全局統(tǒng)一響應(yīng)對象全路徑。比如下面代碼如果配置了returnClass 為GlobalResponse ,那么他生成的yapi 響應(yīng)對象為，GlobalResponse

   /**
     * 測試RequestHeader desc 規(guī)范的多個
     * @param uid 用戶id
     * @status 開發(fā)中 (或者 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 參數(shù)1的名稱或描述
         * @param param2 參數(shù)2的名稱或描述
         * @param param3 參數(shù)3的名稱或描述
         * @return 響應(yīng)描述
         * @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 入?yún)?shù)
         * @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 入?yún)?/p>

/**
 * 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;
}

效果