使用easyYapi生成文档

easyYapi生成文档

• • • 背景
    • 1.安装配置
    • • [1.1 介绍](#1.1 介绍)
      • [1.2 安装](#1.2 安装)
      • [1.3 配置](#1.3 配置)
      • • [1.3.1 Export Postman](#1.3.1 Export Postman)
        • [1.3.2 Export Yapi](#1.3.2 Export Yapi)
        • [1.3.3 Export Markdown](#1.3.3 Export Markdown)
        • [1.3.4 Export Api](#1.3.4 Export Api)
        • [1.3.6 常见问题补充](#1.3.6 常见问题补充)
    • [2. java注释规范](#2. java注释规范)
    • • [2.1 接口注释规范](#2.1 接口注释规范)
      • [2.2 出入参注释规范](#2.2 出入参注释规范)
    • [3. 特定化支持](#3. 特定化支持)
    • • [3.1 必填校验](#3.1 必填校验)
      • [3.2 忽略导出](#3.2 忽略导出)
      • [3.3 返回不一致](#3.3 返回不一致)
      • [3.4 设置header](#3.4 设置header)
      • [3.5 设置tag](#3.5 设置tag)
      • [3.6 设置open](#3.6 设置open)
      • [3.7 序列化相关](#3.7 序列化相关)
    • [4. 自定义配置](#4. 自定义配置)
    • [5. 问题](#5. 问题)

背景

​ 因为公司业务需要接口自动化测试，所以需要针对所有java项目的后端接口进行完整的文档梳理并同步到yapi接口管理平台，在使用swagger实操过程中，发现了一款比较好用的yapi生成工具，特别好用，不仅支持无侵入的方式生成文档，还支持定制化处理。下面一起来就通过笔者的这篇博文来了解EasyYapi这款插件的使用吧。

1.安装配置

1.1 介绍

基于java注释生成api接口文档的idea插件。

• 代码零侵入

• 通过注释生成api接口文档

• 实时生成并同步相关接口平台

• 灵活的配置规则适应项目特性

官方手册 easyYapi

1.2 安装

支持以下IDE

• 2017.3及以上版本。

从IDEA仓库中安装

• Preferences(Settings) --> Plugins > Browse repositories --> find"EasyYapi" --> Install Plugin
  

手动下载安装:

• 下载插件 Jetbrains or Github -> Preferences(Settings) > Plugins > Install plugin from disk...

下载地址： https://plugins.jetbrains.com/

重启IDE

1.3 配置

插件安装完成，可以直接通过在某个类或者某个文件夹下 右键->easyYapi->exportYapi

1.3.1 Export Postman

导出为postman支持的接口信息。

• 直接导出： 导出为json格式的api接口信息 可以导入Postman中

• 配置postman的token导出： 通过在Preferences ---> Other Settings--->EasyApi 中配置postman对应的token 会直接同步到postman上

​ 配置token

​ postman token获取方式

​ https://martian-spaceship-950587.postman.co/integrations/service/pm_pro_api

​ 效果

1.3.2 Export Yapi

​ 导出并同步到yapi服务端。

• 直接导出

​ 首次使用： 需要配置yapi服务端地址 ip+port 和对应yapi分类中的token

​ 1). 配置服务地址

​ 2) . 配置yapi对应分类的token

​ 3). token来源获取

1.3.3 Export Markdown

​ 导出为md文件、直接导出为md文件

1.3.4 Export Api

​ 导出各种类型的请求信息，export api可以针对某个接口进行导出。
##### 1.3.5 call api

Call Api ：生成调试工具 可以进行请求调试调用。

1.3.6 常见问题补充

1. yapi、postman配置错误或者变更： 可通过Preferences ---> Other Settings--->EasyApi修改。
   
2. 导出yapi时 , 每个module需要配置相应的token, 即对应一个yapi中的项目

2. java注释规范

2.1 接口注释规范

\] 表示可选操作 ```java /** * 分类名称 * [分类备注/描述] * * [@module 归属项目] */ @RestController @RequestMapping(value = "/pathOfCtrl") public class MockCtrl { /** * api名称 * [api描述] * [@param param1 参数1的名称或描述] 对于get请求有作用@RequestParam或者@PathVariable有效 * [@param param2 可以用`@link`来表示当前参数的取值是某个枚举{@link some.enum.or.constant.class}] * [@param param3 当目标枚举字段与当前字段名不一致,额外指定{@link some.enum.or.constant.class#property1}] * [@return 响应描述] */ @RequestMapping(value = "/pathOfApi1/${orderCode}") 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 改用{@link #yapi地址}或者{@see #yapi地址}] */ @Deprecated @RequestMapping(value = "/pathOfApi2") public Result methodName2(@RequestBody MockDtoOrVo jsonModel){ ... } } ``` * GET请求的入参@RequestParam或者@PathVariable 中在注释上必须使用@param、出参使用@return。才能生成正常入参文档。 ##### 2.2 出入参注释规范 ```java public class MockDtoOrVo { /** * 字段注释 */ private Long field1; /** * 使用@see来说明当前字段的取值是某个枚举 * @see some.enum.or.constant.enum */ private int field3; /** * 当目标枚举字段与当前字段名不一致,额外指定 * @see some.enum.or.constant.enum#property1 */ private int field4; /** * 可以用注解`@Deprecated`来表示字段被废弃 * 也可以用注释`@deprecated` * @deprecated It's a secret */ @Deprecated private int field5; /** * 如果使用javax.validation的话 * 可以使用@NotBlank/@NotNull表示字段必须 */ @NotBlank @NotNull private String field6; //序列化名称 @JSONField(name="aaa") @JsonAlias("aaa") @JsonProperty("aaa") private String field7; ... } ``` * 字段是常量或者枚举值、可以使用@see 引用枚举，注意枚举、常量对应的类也需要写对应的注释 #### 3. 特定化支持 yapi有对应的通用配置能大致满足我们通用接口的生成，但是针对项目中一些特殊接口，yapi也提供了灵活的运用[配置规则](https://easyyapi.com/setting/index.html) 通过自定义配配置来适应项目特性以减少代码侵入。 * **默认支持的通用配置** ：`Preferences` ---\> `Other Settings`---\>`EasyApi` --\>`Recommend`  ##### 3.1 必填校验 **默认配置** **field.required**: 用于标记字段是否为必须。 默认支持javax.validation annotations。 ​ **param.required:** 用于标记API参数是否为必须。 默认支持javax.validation annotations。 ```sh #get请求入参 [email protected] [email protected] [email protected] #post请求入参 [email protected] [email protected] [email protected] ``` ```java //get请求 入参 @GetMapping("/update/get"） public Map getHttp(Integer fileId) {} //get请求 参数为path @GetMapping("/update/get/{orderCode}") public Map getHttpPath(@PathVariable(name = "orderCode") Integer orderCode) { //@NotBlank @NotEmpty //get请求 参数为path @GetMapping("/update/get"） public Map getHttp(@NotNull Integer fileId) {} //post请求入参属性生成必填 public class AreaUpdateDTO { /** * 区域对象数组 */ @NotNull //@NotBlank //@NotEmpty private List areaList; } ``` **get请求中@RequestParam、@PathVariable修饰的请求参数生成的文档都是必填** **自定义配置** ```java //open接口有这种方法使用 @Validated 如果继续使用@NotNull等注解会破坏现有接口 public ResultBody chCarCorverContractAdd(@Validated @RequestBody CarCoverPromotionContractAddDto dto){ ``` * 自定义注解 ```java /** * 字段必填注解标识 * @author xieqx */ @Target({ElementType.FIELD, ElementType.PARAMETER,ElementType.TYPE}) @Retention(RetentionPolicy.SOURCE) @Documented public @interface CrmFieldRequired { } ``` * 添加自定义配置规则 ```sh #设置字段必填 且支持使用自定义注解 [email protected] [email protected] ``` * 使用 ```java //get请求 @GetMapping("/update/get"） public Map getHttp(@CrmRequired Integer fileId) {} //post请求入参属性生成必填 public class AreaUpdateDTO { /** * 区域对象数组 */ @CrmRequired private List areaList; } ``` ##### 3.2 忽略导出 **ignore**: 整个类或者接口方法不导出。 ```java /** * Mock Apis * @ignore 忽略当前类 */ @RestController @RequestMapping(value = "mock") public class MockCtrl { /** * Mock String * @ignore 忽略当前api */ @GetMapping("/string") public String mockString() { return Result.success("mock string"); } } ``` **field.ignore**:字段忽略不导出。 默认支持如下 ```sh #字段级别导出 [email protected]#value [email protected]#serialize ``` * **自定义注解** ```java /** * 字段忽略注解 * @author xieqx */ @Target({ElementType.FIELD, ElementType.PARAMETER,ElementType.TYPE}) @Retention(RetentionPolicy.SOURCE) @Documented public @interface CrmFieIdIgnore { } ``` **自定义配置** ```sh [email protected] [email protected] ``` ##### 3.3 返回不一致 \*\*method.return: \*\* 设置方法的返回值。 > 常用于以下情况: * 方法响应统一封装 * 方法返回Object * 方法返回类型中的泛型类型未明确`