IDEA使用YapiUpload插件自动生成Yaip接口文档

 

一、下载安装

1.通过链接下载YapiUpload，手动导入到idea

https://plugins.jetbrains.com/files/12276/98753/YapiUpload.jar?updateId=98753&pluginId=12276&family=INTELLIJ&uuid=5fda8998-e6dd-4d47-a0f7-1d519d9182b4&code=IU&build=182.3684.101

2.下载完后进入idea插件库手动导入disk

3.选择YapiUpload.jar

4.重启idea

二、配置

1.在项目目录下，.idea 文件夹下，找到misc.xml

2. 单模块配置 

<component name="yapi">
  <option name="projectToken">yapi 中项目token</option>
  <option name="projectId">yapi 中项目id</option>
  <option name="yapiUrl">http://127.0.0.1:3000</option>
  <option name="projectType">api</option>
  <option name="attachUploadUrl">http://localhost/fileupload</option>
  <option name="returnClass">com.project.Response(1.7.4 及之后才支持,按需配置)</option>
</component>

3.多模块配置

<component name="yapi">
    <option name="moduleList">moduleName1,moduleName2</option>
  </component>

  <component name="moduleName1">
      <option name="moduleName1.projectToken">yapi 中项目token</option>
      <option name="moduleName1.projectId">yapi 中项目id</option>
      <option name="moduleName1.yapiUrl">http://127.0.0.1:3000</option>
      <option name="moduleName1.projectType">api</option>
      <option name="moduleName1.attachUploadUrl">http://localhost/fileupload</option>
      <option name="moduleName1.returnClass">com.project.Response</option>
  </component>

4.各个参数获得 

• projectToken：打开yapi ->具体项目->设置->token 配置
• projectId：点击项目，查看url 中project 后面的数字为项目id http://127.0.0.1:3000/project/72/interface/api
• yapiUrl：部署的yapi 地址
• projectType：根据你要上传的接口类型决定，如果为dubbo 接口就填dubbo ，如果是api 接口就填api
• attachUploadUrl ：上传java 类zip 的url,如果要用请实现http://localhost/fileupload 接口 接口请求参数为 file 文件类型。(可不填)
• returnClass：统一返回对象的全路径（1.7.4及之后支持,之前版本可不配)
• moduleList：模块名称，用 "," 分割 ，不支持父节点和子模块名称一样的情况

示例：

5.生成文档

api 项目，选中controller 类中的方法名称或类名（要选中方法名称，或类名，选中类名为当前类所有接口都上传），右击YapiUpload(alt+u快捷键)

三、文档生成规则

1.生成接口名称（接口上的注释）

    /**
     * 查询公告
     * @param user
     * @return
     */
    @RequestMapping(value = "/getNotice", method = RequestMethod.POST)
    @ResponseBody
    public ReturnMessage<Notice> YapiUploadDemo(@RequestBody NoticeParam noticeparam){
        Notice notice = noticeService.searchNotice(noticeparam);
        return new ReturnMessage(200,"查询成功",notice );
    }

    //"查询公告"为接口名称，POST为请求方式

2.生成属性备注（字段备注中的注释）

    /**
     * 公告名称
     */
    private String noticename;

3.定义接口分类

通过在方法或类注释中加 @menu 注释实现，优先级 方法>类>package 下面或者上面的@menu,如果没有自定义 默认为tool-tmp

package com.notice;
/** 
 *@menu 分类名称(类上面添加分类名称后默认所有方法都在该分类)
 */   
@RestController
public class NoticeController {

    /**
     * @param Notice
     * @menu 这里填写方法级别分类名称 比如 多级目录/menu/menu1/menu2
     * @return
     */
     @RequestMapping(value = "/addNotice", method = RequestMethod.POST)
     public Response<Notice> addNotice(@RequestBody Notice notice){
    
    }
}

4.通过注解设置字段可否为空

    /**
     * 公告名称
     */
    @NotEmpty
    private String noticename;

    /**
     * 发布时间
     */
    @NotNull
    private String publishtime;


    //不加注解默认为可空

---

参考文章：https://github.com/diwand/YapiIdeaUploadPlugin/wiki/%E5%BF%AB%E9%80%9F%E4%BD%BF%E7%94%A8