使用easyYapi生成文档

news2024/11/14 19:13:03

easyYapi生成文档

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

[] 表示可选操作

/**
 * 分类名称
 * [分类备注/描述]
 *
 * [@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 出入参注释规范
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也提供了灵活的运用配置规则 通过自定义配配置来适应项目特性以减少代码侵入。

  • 默认支持的通用配置Preferences —> Other Settings—>EasyApi -->Recommend
    在这里插入图片描述
3.1 必填校验

默认配置

field.required: 用于标记字段是否为必须。 默认支持javax.validation annotations。

param.required: 用于标记API参数是否为必须。 默认支持javax.validation annotations。

#get请求入参
param.required=@javax.validation.constraints.NotBlank
param.required=@javax.validation.constraints.NotNull
param.required=@javax.validation.constraints.NotEmpty

#post请求入参
field.required=@javax.validation.constraints.NotBlank
field.required=@javax.validation.constraints.NotNull
field.required=@javax.validation.constraints.NotEmpty
//get请求 入参 
@GetMapping("/update/get"public Map<String, Object> getHttp(Integer fileId) {}

//get请求 参数为path            
@GetMapping("/update/get/{orderCode}")
public Map<String, Object> getHttpPath(@PathVariable(name = "orderCode") Integer orderCode) {

//@NotBlank  @NotEmpty  
//get请求 参数为path 
@GetMapping("/update/get"public Map<String, Object> getHttp(@NotNull Integer fileId) {}


//post请求入参属性生成必填
public class AreaUpdateDTO {
    /**
     * 区域对象数组
     */
    @NotNull
    //@NotBlank
    //@NotEmpty
    private List<AreaDTO> areaList;
 }

get请求中@RequestParam、@PathVariable修饰的请求参数生成的文档都是必填

自定义配置

//open接口有这种方法使用 @Validated 如果继续使用@NotNull等注解会破坏现有接口
public ResultBody<ContractAddResultDTO4Open> chCarCorverContractAdd(@Validated @RequestBody CarCoverPromotionContractAddDto dto){
  • 自定义注解
/**
 * 字段必填注解标识
 * @author xieqx
 */
@Target({ElementType.FIELD, ElementType.PARAMETER,ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
@Documented
public @interface CrmFieldRequired {
}
  • 添加自定义配置规则
#设置字段必填 且支持使用自定义注解
field.required=@com.yiche.crm.base.annotations.CrmFieldRequired

param.required=@com.yiche.crm.base.annotations.CrmFieldRequired
  • 使用
//get请求
@GetMapping("/update/get"public Map<String, Object> getHttp(@CrmRequired Integer fileId) {}

//post请求入参属性生成必填
public class AreaUpdateDTO {
    /**
     * 区域对象数组
     */
    @CrmRequired
    private List<AreaDTO> areaList;
}
3.2 忽略导出

ignore: 整个类或者接口方法不导出。

/**
* 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:字段忽略不导出。

默认支持如下

#字段级别导出
field.ignore=@com.fasterxml.jackson.annotation.JsonIgnore#value
field.ignore=!@com.google.gson.annotations.Expose#serialize
  • 自定义注解
/**
 * 字段忽略注解
 * @author xieqx
 */
@Target({ElementType.FIELD, ElementType.PARAMETER,ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
@Documented
public @interface CrmFieIdIgnore {
}

自定义配置

field.ignore=@com.yiche.crm.base.annotations.CrmFieIdIgnore
param.ignore=@com.yiche.crm.base.annotations.CrmFieIdIgnore
3.3 返回不一致

**method.return: ** 设置方法的返回值。

常用于以下情况:

  • 方法响应统一封装
  • 方法返回Object
  • 方法返回类型中的泛型类型未明确<Object>/<?>/<*>
  • 方法返回类型与实际响应无关, 例如通过操作HttpServletResponse来返回响应

目前特殊接口

crm系统中大部分的请求出参情况如下:

//1.返回泛型未明确
public ResultBody getSpecialApprovalAttach()//2.出参与响应不一致
@CommonResult
public String getHttpPath()  
@CommonResult
public PageInfo<Student> getHttpPath()
@CommonResult
public List<Student> getHttpPath()     
  
//3.下载导出
@CommonResult
public void download(HttpserveletResponse resp)   

自定义配置规则

#该配置的意思是 无论返回值是怎样的只需在注释中使用@real_return 后引入真实的对象类型即可
#it.doc("real_return") 中real_return自定义字符串即可(最好项目统一)
method.return[#real_return] =
  groovy: "com.yiche.crm.common.rest.ResultBody<" +  helper.resolveLink(it.doc("real_return")) +">"
    
#对于只返回单个字段 
#method.return.main[groovy:it.returnType().isExtend("com.yiche.crm.common.rest.ResultBody")]=data 
  • 使用
//1.返回泛型未明确
/**
 * @real_return  {@link String}
 */
public ResultBody getSpecialApprovalAttach(){
    return ResultBody.ok("hello");
}
  
//2.出参与响应不一致
/**
 * @real_return  {@link String}
 */
@CommonResult
public String getHttpPath() {
  return "hello"
} 
/**
 * @real_return  {@link PageInfo<Student>}
 */
@CommonResult
public PageInfo<Student> getHttpPath()

/**
 * @real_return  {@link List<Student>}
 */  
@CommonResult
public List<Student> getHttpPath()     
  
//3.下载导出
/**
 * @real_return  {@link void}
 * 或者
 * @real_return  {@link com.alibaba.excel.EasyExcel}
 */    
@CommonResult
public void download(HttpserveletResponse resp)   
3.4 设置header

method.additional.header: API需要额外的header

  • 配置
#所有接口都需要设置如下header
#method.additional.header={name: "Authorization",value: "",desc: "认证Token",required:true, example:""}

api.tag=@open_header

# 特定的接口需要添加header
# 对于注释使用@open_header的接口 需要特定的header(主要针对crm系统open接口)
method.additional.header[groovy:it.hasDoc("open_header")]={name: "token",value: "",desc: "认证Token",required:true}
method.additional.header[groovy:it.hasDoc("open_header")]={name: "source",value: "",desc: "来源,接口调用方",required:true}

# 对于注释使用@open_yxs_header的接口 需要特定的header(主要针对crm系统open-yxs接口)
method.additional.header[groovy:it.hasDoc("open_yxs_header")]={name: "x-access-ework-token",value: "",desc: "鉴权token",required:true}

  • 使用
/**
 *
 * @open_header 添加open_header配置的header
 * @open_yxs_header 添加open_yxs_header配置的header
 */
@GetMapping("/update/download")
@CommonResult
public ResultBody download(HttpServletResponse response){}
3.5 设置tag

api.tag: 标记接口,脚本中可以使用it.getDoc(“tagNam”)获取到。

  • 配置
#语法 [#标记的名字] --- 注释中写@tagLabel 在yapi的tag中显示tagName
api.tag[#tagLabel]=tagName

api.tag=@open_header
  • 使用
/**
 *
 * @open_header 添加open_header配置的header
 * @deprecated 注释中使用
 */
@Deprecated  //java注解
@GetMapping("/update/download")
@CommonResult
public ResultBody download(HttpServletResponse response){}
3.6 设置open

api.tag: 标记接口是否公开,从yapi导出api的时候可以选择只导出开放接口的api。

  • 配置
#配置方式
api.open=#open
api.open=#myTag
  • 使用
/**
 *
 * @open
 * 或者
 * @myTag
 */
@GetMapping("/update/download")
public Map<String, Object> areaUpdateNotice(@RequestBody AreaUpdateDTO dto) {
3.7 序列化相关

字段名称与返回的类型不一致的问题

@JSONField(name="aaa")
@JsonAlias("aaa")
@JsonProperty("aaa")
private Integer status;

easyYapi默认支持@JsonProperty(“aaa”)的转换,其他转换需要配置

#支持@JSONField注解
field.name=@com.alibaba.fastjson.annotation.JSONField#name

#支持@JsonAlias注解
field.name=@com.fasterxml.jackson.annotation.JsonAlias#value

4. 自定义配置

设置字段必填 且支持使用自定义注解
field.required=@com.yiche.crm.base.annotations.YapiRequired

#是否开放接口 不设置默认 非开放
api.open=#open
api.open=#xiu

#设置标签
#api.tag[#xiu]=my_tag
api.tag=@open_header
api.tag=@open_yxs_header

# 对于注释使用@的接口 需要特定的header(主要针对crm系统open接口)
method.additional.header[groovy:it.hasDoc("open_header")]={name: "token",value: "",desc: "认证Token",required:true}
method.additional.header[groovy:it.hasDoc("open_header")]={name: "source",value: "",desc: "来源接口调用方",required:true}


# 对于注释使用@open的接口 需要特定的header(主要针对crm系统open_yxs接口)
method.additional.header[groovy:it.hasDoc("open_yxs_header")]={name: "x-access-ework-token",value: "",desc: "易小鲨认证Token",required:true}

#支持@JSONField注解
field.name=@com.alibaba.fastjson.annotation.JSONField#name

#支持@JsonAlias注解
field.name=@com.fasterxml.jackson.annotation.JsonAlias#value

5. 问题

  • Map、JsonObject问题处理

  • 必填校验,如果多个接口使用同一个入参,必填字段不一样使用必填注解也是有问题的

  • 返回单个字段 无法设置注释

  • Postman 调试添加用例

  • yapi整合测试、mock、生成测试报告

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.coloradmin.cn/o/1536549.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

【单调队列】第十四届蓝桥杯省赛C++ C组 Java C组/研究生组 Python A组《子矩阵》(C++)

【题目描述】 给定一个 nm &#xff08;n 行 m 列&#xff09;的矩阵。 设一个矩阵的价值为其所有数中的最大值和最小值的乘积。 求给定矩阵的所有大小为 ab &#xff08;a 行 b 列&#xff09;的子矩阵的价值的和。 答案可能很大&#xff0c;你只需要输出答案对 998244353…

羽毛球移动步法训练

文章目录 简介训练量01 小颠步02 左右并步03 交叉步04 前后并步05 高抬腿06 高抬腿转髋07 左右移动跳08 并步跳09 前后小密步10 弓箭步跳11 开合跳参考文献 简介 本文参考&#xff1a;陈金羽毛球移动专项步法训练&#xff08;BV1cS4y1V7xA&#xff09;和颜叨叨的移动专项步法跟…

数据表练习

思维导图 面试题答问1、IO多路复用的引入目的和原理 目的&#xff1a;在有操作系统时&#xff0c;可以用多线程和进程完成任务并发执行&#xff0c;没有操作系统的情况下可以使用IO多路复用技术来进行任务并发。 原理&#xff1a;将多个阻塞任务的文件描述符统一放到一个检查容…

Qt 容器类控件

Group Box 使用 QGroupBox 实现一个带有标题的分组框可以把其他的控件放到里面作为一组&#xff0c;这样看起来能更好看一点. 核心属性 属性说明title分组框的标题alignment分组框内部内容的对齐方式flat是否是 “扁平” 模式checkable是否可选择. 设为 true&#xff0c;则在…

Golang基础知识(笔记迁移)

golang 变量作用域 局部作用域&#xff1a;代码块、函数内的全局作用域&#xff1a;顶层作用域&#xff0c;代码块外的就是全局&#xff0c;如果变量名大写&#xff0c;则改变量整个程序都可以使用。 类型断言 golang的类型断言在变量后加上.(type)&#xff0c;如果类型断言…

【Android】系统启动流程分析 —— init 进程启动过程

本文基于 Android 14.0.0_r2 的系统启动流程分析。 一、概述 init 进程属于一个守护进程&#xff0c;准确的说&#xff0c;它是 Linux 系统中用户控制的第一个进程&#xff0c;它的进程号为 1&#xff0c;它的生命周期贯穿整个 Linux 内核运行的始终。Android 中所有其它的进程…

python5:基于多进程的并发编程、基于协程的并发编程的学习笔记

进程 为什么要使用多进程&#xff1f;——GIL的存在&#xff0c;多线程实际不是并发执行 将任务分为两类&#xff1a;IO密集型&#xff08;多线程&#xff09;CPU密集型&#xff08;多进程&#xff09; 多进程的基本用法 concurrent.futures.process.ProcessPoolExecutor#进…

移除和替换任何内容:AI 驱动的图像修复工具 | 开源日报 No.204

Sanster/IOPaint Stars: 15.1k License: Apache-2.0 IOPaint 是一款由 SOTA AI 模型驱动的图像修复工具。 该项目解决了从图片中移除任何不需要的对象、瑕疵或人物&#xff0c;以及擦除和替换图片上任何内容&#xff08;由稳定扩散技术支持&#xff09;的问题。 完全免费且开…

ETH Denver 2024 精彩回顾|波卡,远不止一个区块链

ETH Denver 2024 于 2 月 23 日至 3 月 3 日在美国丹佛举行&#xff0c;该活动由 SporkDAO 主办&#xff08;SporkDAO 是一个来自美国科罗拉多州的 Web3 公益开发者组织&#xff0c;其前身或者说起源就是 ETHDenver&#xff0c;后随着组织发展逐渐转变为 DAO 开展了研究、投资等…

YOLO-v8-seg实例分割使用

最近需要实例分割完成一些任务&#xff0c;一直用的SAM(segment anything&#xff09;速度慢&#xff0c;找一个轻量分割模型。 1. YOLO-v8-seg使用 git clone https://github.com/ultralytics/ultralytics.git cd ultralytics vim run.py from ultralytics import YOLO# L…

JS加密解密之字符编码知识

在前端开发中&#xff0c;字符编码是一个至关重要的概念&#xff0c;特别是在数据传输、加密和解密等方面。JavaScript作为一种常用的脚本语言&#xff0c;在处理字符编码时也有其独特之处。本文将详细介绍JavaScript中的字符编码知识&#xff0c;包括字符编码的分类和相关案例…

【C++】1600. 请假时间计算

问题&#xff1a;1600. 请假时间计算 类型&#xff1a;基本运算、整数运算 题目描述&#xff1a; 假设小明的妈妈向公司请了 n 天的假&#xff0c;那么请问小明的妈妈总共请了多少小时的假&#xff0c;多少分钟的假&#xff1f;&#xff08;提示&#xff1a; 1 天有 24 小时&…

2_27. 移除元素

2_27. 移除元素 难度: 简单 提示: 给你一个数组 nums 和一个值 val&#xff0c;你需要 原地 移除所有数值等于 val 的元素&#xff0c;并返回移除后数组的新长度。 不要使用额外的数组空间&#xff0c;你必须仅使用 O(1) 额外空间并 原地 修改输入数组。 元素的顺序可以改变…

知识管理入门:轻松选择合适的知识管理软件

你是不是经常觉得自己的大脑像个杂乱的仓库&#xff0c;各种信息、知识和想法在里面乱窜&#xff0c;找不到头绪&#xff1f;别担心&#xff0c;知识管理软件来帮你解决这个问题啦&#xff01;今天&#xff0c;我们就来聊聊知识管理软件这个神奇的工具&#xff0c;新手也能轻松…

python基础——语句

一、条件语句 就是 if else 语句 &#xff01; 代表不等于 代表等于if 关键字&#xff0c;判断语句&#xff0c;有“如果”的意思&#xff0c;后面跟上判断语句else 常和“if” 连用&#xff0c;有“否则”的意思&#xff0c;后面直接跟上冒号 …

华为配置WLAN 802.1X认证实验

配置WLAN 802.1X认证示例 组网图形 图1 配置802.1X认证组网图 业务需求组网需求数据规划配置思路配置注意事项操作步骤 业务需求 用户接入WLAN网络&#xff0c;使用802.1X客户端进行认证&#xff0c;输入正确的用户名和密码后可以无线上网。且在覆盖区域内移动发生漫游时&…

鸿蒙一次开发,多端部署(三)应用UX设计原则

设计原则 当为多种不同的设备开发应用时&#xff0c;有如下设计原则&#xff1a; 差异性 充分了解所要支持的设备&#xff0c;包括屏幕尺寸、交互方式、使用场景、用户人群等&#xff0c;对设备的特性进行针对性的设计。 一致性 除了要考虑每个设备的特性外&#xff0c;还…

vue3 reactive丢失响应式

问题 使用 reactive 构造响应式对象时&#xff0c;当对其进行重新赋值后&#xff0c;会导致原有变量失去响应式&#xff0c;页面不会发生联动更新 例如&#xff1a; 1、使用 reactive 定义一个响应式的对象变量 let data1 reactive({name: 小李,date: 2024-03-18,address: xx…

基于Python的HTTP接口自动化测试框架实现

对服务后台一系列的http接口功能测试。 输入&#xff1a;根据接口描述构造不同的参数输入值 输出&#xff1a;XML文件 二、实现方法 1、选用Python脚本来驱动测试 2、采用Excel表格管理测试数据&#xff0c;包括用例的管理、测试数据录入、测试结果显示等等&#xff0c;这…

美团2023年财报:全年营收2767亿元,即时配送订单219亿笔

3月22日&#xff0c;美团(股票代码:3690.HK)发布2023年第四季度及全年业绩。公司各项业务继续取得稳健增长&#xff0c;全年营收2767亿元(人民币&#xff0c;下同)&#xff0c;同比增长26%&#xff0c;经营利润134亿元。 本年度&#xff0c;美团继续围绕“零售科技”战略&…