YApi 接口同步插件使用说明

YApi 接口同步插件使用说明

写在前面（ Foreword ）

此插件主要用于工程代码同步至 YApi 接口平台，以便查看接口状态和信息。同步接口时，请自觉维护好接口列表

快速上手（ Getting Started ）

下载YApiSync.jar,打开 idea preferneces->plugins-> install plugin from disk,导入 jar 包后(install)，重启
先登录 YApi 平台，使用域账号登陆（基于LDAP认证登陆）
配置信息

配置信息位置, 在项目目录下，.idea 文件夹下，找到 misc.xml (如果找不到.idea 请查看是否被折叠或被隐藏) 如果是 .ipr 模式创建的就找到项目名.ipr

  <component name="yapi">
    <option name="projectToken">用户项目的Token</option>
    <option name="projectId">用户项目ID</option>
    <option name="yapiUrl">http://xxx.xxx.xxx.xxx:3000</option>
    <option name="projectType">api</option>
  </component>

  <!-- 中台管理台接口平台配置示例 -->
  <component name="yapi">
    <option name="projectToken">4a948bd3ea80a842d30b5f3d8ee855615dc177924d495e441a0802d1cff9b02f</option>
    <option name="projectId">50</option>
    <option name="yapiUrl">http://xxx.xxx.xxx.xxx:3000</option>
    <option name="projectType">api</option>
  </component>

同步

如果是 dubbo 项目，选中 dubbo interface 文件中的一个方法（要选中方法名称），右击 YApiSync(ALT+U 快捷键)
如果是 api 项目，选中 controller 类中的方法名称或类名（要选中方法名称，或类名，选中类名为当前类所有接口都同步），右击 YApiSync(ALT+U 快捷键)
如果是 component/intf 项目，选中接口的方法名称或类名（要选中方法名称，或类名，选中类名为当前类所有接口都上传），右击 YApiUpload(ALT+U 快捷键)
如果是选中文件夹或者多个文件，右键或者快捷键(SHIFT+ALT+U)支持批量同步

选中

双击方法或类名即为选中, 如果未选择任何地方同步默认按类(Idea未分类接口)同步

JavaDoc注释规范与约定

良好的 java doc 注释能更清晰的生成更好的文档

生成属性备注

/**
 * 姓名
 */
private Integer name;

生成接口名称

第一种方式
    /**
     * 产品列表
     *
     * @param request
     * @return
     */
    @PostMapping("/queryPage")
    public CommonResponse<PageInfo<ProductDto>> queryPage(@RequestBody QueryProductListRequestDto request) {

    }

第二种方式
    /**
     * 产品列表(如果描述过多，把文字放在这里，这种情况下实际使用的是@name的方法名称）
     *
     * @param request
     * @return
     * @name 产品列表查询
     */
    @PostMapping("/queryPage")
    public CommonResponse<PageInfo<ProductDto>> queryPage(@RequestBody QueryProductListRequestDto request) {

    }

@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;

实现自定义分类

通过在方法或类注释中加 @name 注释实现，优先级方法>类>package 下面或者上面的@name, 如果没有自定义默认为 Idea未分类接口

这里如没必要，我们只使用类上面的@name即可；

package com.project.demo;

import com......

/**
 * 产品查询
 * 如果没有@name，那么使用这里的说明；
 * 如果类的文字说明过多时，则可以把名称放在@name下；
 *
 * @author ridup.cn
 * @version V3.0
 * @name 产品查询（先匹配这里）
 * @since 3.0.1  2020/6/11  19:32
 */
@RestController
@RequestMapping(RESTFULConstant.MODULE_OPERATION_PREFIX + "/v1/productQuery")
public class ProductQueryController {

}

支持的注解

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

支持@status 注解

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

    /**
     * 产品详情查询
     *
     * @param request
     * @return
     * @status done
     */
    @PostMapping("/queryProductDetail")
    public CommonResponse<XXXResponseDto> queryProductDetail(
        @RequestBody XXXRequestDto request) {
    }

支持Swagger

支持以下注解


  String API_OPERATION = "io.swagger.annotations.ApiOperation";

  String API_MODEL_PROPERTY = "io.swagger.annotations.ApiModelProperty";

  String API_PARAM = "io.swagger.annotations.ApiParam";

支持@path

在方法上指定路径，通过@path 注释, 如下代码，其生成的路径为/path/xxxx/queryProductDetail

    /**
     * 产品详情查询
     * @path /path/xxxx/queryProductDetail
     * @param request
     * @return
     * @status done
     */
    @PostMapping("/queryProductDetail")
    public CommonResponse<XXXResponseDto> queryProductDetail(
        @RequestBody XXXRequestDto request) {
    }

aaa

pencui/YApiSyncPlugin