IDEA-EasyYapi的使用（快速生成接口文档）

曾经终败给现在 2023-10-07 16:25 43阅读 0赞

链接: [EasyYapi官方文档][EasyYapi].

### 下载插件 ###

下载EasyYapi插件

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70]

### 重启IDEA，配置EasyYapi ###

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 1]

### 获取token ###

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 2]

### 使用 ###

快捷键 Alt+insert

![在这里插入图片描述][2021052617541581.png]

### 自定义参数，如 额外要求header中携带token ###

链接: [demo][].  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 3]

文件名称为：.easy.api.config  .不能少
    文件必须放在最外层

#额外要求header中携带token
    method.additional.header[groovy:!it.hasAnn("com.xxx.xxx.Public")]={
        name: "token",value: "",desc: "token",required:true, example:""}

#### 创建注解，以注解进行判断是否需要添加自定义参数 ####

链接: [method.additional.header][].

package com.itangcent.common.annotation;
    import java.lang.annotation.*;
    
    /**
     * YApi声明接口为公开接口
     */
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target({
        ElementType.TYPE, ElementType.METHOD})
    public @interface Public {
        
    }

/**
    * Mock Apis
    */
    @RestController
    @RequestMapping(value = "mock")
    public class MockCtrl {
        
    
        /**
        * public api
        * Token is not required
        */
        @Public
        @GetMapping("/apiWithoutToken")
        public Result<String> apiWithoutToken() {
        
            return Result.success("no token");
        }
    
        /**
        * private api
        * Token is required
        */
        @GetMapping("/apiWithToken")
        public Result<String> apiWithToken() {
        
            return Result.success("wow,you got a token");
        }
    
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 4]

### Java注释规范(配合EasyYapi使用) ###

api demo
    
    /**
     * 分类名称
     * 分类备注/描述
     *
     * @module 归属项目
     */
    @RestController
    @RequestMapping(value = "/pathOfCtrl")
    public class MockCtrl {
        
    
        /**
        * api名称
        * api描述
        * @param param1 参数1的名称或描述
        * @param param2 可以用`@link`来表示当前参数的取值是某个枚举{@link some.enum.or.constant.class}
        * @param param3 当目标枚举字段与当前字段名不一致,额外指定{@link some.enum.or.constant.class#property1}
        * @return 响应描述
        */
        @RequestMapping(value = "/pathOfApi1")
        public Result methodName1(long param1,
                          @RequestParam String param2,
                          @RequestParam(required = false, defaultValue = "defaultValueOfParam3") String param3){
        
            ...
        }
    
    
        /**
        * 默认使用`application/x-www-form-urlencoded`,
        * 对于`@RequestBody`将使用`application/json`
        * 可以用注解`@Deprecated`来表示api废弃
        * 也可以用注释`@deprecated`
        *
        * @deprecated 改用{@link #methodName3(String)}
        */
        @Deprecated
        @RequestMapping(value = "/pathOfApi2")
        public Result methodName2(@RequestBody MockDtoOrVo jsonModel){
        
            ...
        }
    
        /**
        * 所有注释或者参数描述中都可以使用`@link`来引用另一个API
        * 例如:
        * 请先访问{@link #methodName4(String)}
    
        * 也可以使用`@see`来引用另一个API
        *
        * @param param1 参数1的名称或描述 可以从{@link #methodName5(String)}中获得
        * @see #methodName6(String)
        * @deprecated 改用{@link #methodName7(String)}
        */
        @Deprecated
        @RequestMapping(value = "/pathOfApi3")
        public Result methodName3(long param1){
        
            ...
        }
    
        ...
    }
    model(dto/vo) demo
    public class MockDtoOrVo {
        
    
        /**
         * 字段注释
         */
        private Long field1;
    
        private Double field2;//注释也可以写在这
    
        /**
         * 使用@see来说明当前字段的取值是某个枚举
         * @see some.enum.or.constant.class
         */
        private int field3;
    
        /**
         * 当目标枚举字段与当前字段名不一致,额外指定
         * @see some.enum.or.constant.class#property1
         */
        private int field4;
    
        /**
         * 可以用注解`@Deprecated`来表示字段被废弃
         * 也可以用注释`@deprecated`
         * @deprecated It's a secret
         */
        @Deprecated
        private int field5;
    
        /**
         * 如果使用javax.validation的话
         * 可以使用@NotBlank/@NotNull表示字段必须
         */
        @NotBlank
        @NotNull
        private String field6;
    
        ...
    }

[EasyYapi]: http://easyyapi.com/documents/index.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20210526175001513.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20210526175226841.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20210526175046956.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw,size_16,color_FFFFFF,t_70
[2021052617541581.png]: https://img-blog.csdnimg.cn/2021052617541581.png
[demo]: https://github.com/Earth-1610/spring-demo/tree/master/cn
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20210526175545736.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw,size_16,color_FFFFFF,t_70
[method.additional.header]: http://easyyapi.com/setting/rules/method_additional_header.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20210526175846195.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNjA0ODkw,size_16,color_FFFFFF,t_70