SpringBoot使用EasyYapi对代码0侵入实现API接口一键发布到YApi的进阶使用 - 第423篇

在前面的小节中,我们介绍了EasyYapi插件的使用,但在实际项目中,如果只是学习到这里是远远不够的,所以这一节的话,我们会解答前一小节遗留的问题:如何设置参数是必需的以及EasyYapi的进阶使用。

一、EasyYapi的注释规范

         在前面小节中,我们使用EasyYapi插件可以一键发布到YApi平台,在代码中并没有做任何的配置,那么是EasyYapi是如何工作了?

         EasyYapi核心就是抓取到了javadoc的注释。

1.1 类上的注释-分类的信息

         在类上面的注释,对应的是YApi的分类的信息,看下如下代码:

/** * * 订单管理(分类名称) * 对订单的基本操作(分类备注/描述) * * @module springboot-vide-demo * @author 悟纤「公众号SpringBoot」 * @date 2022-03-21 * @slogan 大道至简 悟在天成 */@RestController@RequestMapping("/order")public class OrderController {}

说明:

(1)第一行默认是接口的分类名称。

(2)第二行到第一个以@开头的行之前的为分类的描述。

(3)@module用于分类api

n  导出postman时 , 每个module将作为一个单独的文件夹

n  导出yapi时 , 每个module需要配置相应的token, 即对应一个yapi中的项目

n 默认情况下取当前模块名(单模块项目取项目名)

所以当要导出到YApi的时候,那么@module就是对应的YApi配置的项目。至于说项目的名称叫什么这个不重要,重要的是项目对应的token:

这里我们重新定义了@module为在YApi设置的项目<多音短视频项目>,那么在发布的时候,就需要填写对应的Token(token怎么找,在上一节有说过):

         这样就会发布到<抖音音短视频项目>:

特别说明:没有特殊情况下,这个@module就不要配置了。

         另外我们可以看下分类的备注:

1.2 方法上的注释-接口信息

         方法上的注释,对应YApi的接口信息,看如下代码:

/** * 测试方法1(api名称) * 这个是测试方法的描述(api描述) * * @param param1 参数1的名称或描述 * @param param2 可以用`@link`来表示当前参数的取值是某个枚举{@link OrderInfo} * @param param3 参数3的名称或描述 * @return 响应描述 */@RequestMapping("/method1")public String method1(long param1,                      @RequestParam  String param2,                      @RequestParam(required = true,defaultValue = "defaultValueOfParam3") String param3){    return "SUCCESS";}

(1)第一行默认是接口的名称。

(2)第二行到第一个以@开头的行之前的为接口的描述。

(3)@param 是参数的信息

(4)@return 是返回的信息

         看下对应的YApi的显示:

         点击进去看下详情:

         这里我们能看出如果参数要默认是必须的话,那么使用注解@RequestParam即可实现了。

1.2 方法上的参数是引用类型

         我们的saveOrder的参数是引用类型:

  我们的saveOrder的参数是引用类型:/** *  保存订单 * @param orderInfo * @return */@RequestMapping("/saveOrder")public OrderInfo saveOrder(OrderInfo orderInfo){    return orderInfo;}

         对应的OrderInfo:

/** * 订单信息 * * @author 悟纤「公众号SpringBoot」 * @date 2022-03-21 * @slogan 大道至简 悟在天成 */public class OrderInfo {    private int oid;    private int uid;    private int shopId;    private Date createTime;    public int getOid() {        return oid;    }    public void setOid(int oid) {        this.oid = oid;    }    public int getUid() {        return uid;    }    public void setUid(int uid) {        this.uid = uid;    }    public int getShopId() {        return shopId;    }    public void setShopId(int shopId) {        this.shopId = shopId;    }    public Date getCreateTime() {        return createTime;    }    public void setCreateTime(Date createTime) {        this.createTime = createTime;    }}

         这样的情况下,我们在YApi得到的结果是:

         明显这里的参数的字段都没有备注,以及是否必须都是否。对于这个问题,我们只需要在OrderInfo上进行添加即可注释即可,对于是否必须,需要使用到注解@NotNull,那么需要添加依赖(Spring Boot项目):

<dependency>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-starter-validation</artifactId></dependency>

         OK,好了整体的代码如下:

import javax.validation.constraints.NotBlank;import javax.validation.constraints.NotNull;import java.util.Date;/** * 订单信息 * * @author 悟纤「公众号SpringBoot」 * @date 2022-03-21 * @slogan 大道至简 悟在天成 */public class OrderInfo {    /**     * 订单的id     */    @NotNull    private int oid;    @NotBlank    private int uid;//创建订单的用户(注释也可以写在这里)    @NotNull    private int shopId;//商品的id.    private Date createTime;//创建时间    public int getOid() {        return oid;    }    public void setOid(int oid) {        this.oid = oid;    }    public int getUid() {        return uid;    }    public void setUid(int uid) {        this.uid = uid;    }    public int getShopId() {        return shopId;    }    public void setShopId(int shopId) {        this.shopId = shopId;    }    public Date getCreateTime() {        return createTime;    }    public void setCreateTime(Date createTime) {        this.createTime = createTime;    }}

说明:如果使用javax.validation的话,可以使用@NotBlank/@NotNull表示字段必须。

         看下效果:

二、EasyYapi的Call Api

打开项目中的包含api的文件, 右键文件内容选择选择Call Api, 即可通过窗口进行api请求:

         好像不是很好用。

三、EasyYapi进阶使用

3.1 @ignore忽略API

         当在接口注释使用 @ignore时候,导出被忽略:

3.2字段被废弃

用注释`@deprecated`来表示字段被废弃:

/** * 创建时间 * @deprecated */private Date createTime;

YApi显示效果:

         当然在属性上添加注解@Deprecated也有类似的效果:

/** * 创建时间 */@Deprecatedprivate Date createTime;



YApi显示效果:

         细观察微微还是有不同的区别的,少了一个换行,O(∩_∩)O哈哈~

3.3 本地配置文件

支持的规则(截取一部分):

3.3.1 如何配置

         将配置文件添加到项目或模块根目录中:  

         这里我们使用.easy.api.config的文件,在项目根目录进行创建:

温馨提示:.不能少。

3.3.2 api.name

用于设置API名称

缺省情况下,默认使用api注释的第一行作为API的名称

         我们在配置文件.easy.api.config添加配置:

# read api name from tag `api.name`api.name=#api.name

         那么就可以在注解上进行使用:

说明:当配置了@api.name之后,就不需使用第一行作为API的名称了;当未配置@api.name的话,使用注释的第一行作为API的名称。

3.3.3 api.status

         这个就是状态了,默认都是已完成的:

         那么要修改未完成如何操作:

                   我们在配置文件.easy.api.config添加配置:

#yapi statusapi.status[#undone]=undoneapi.status[#todo]=undone

         那么就可以在注解上进行使用:

         在YApi查看的结果(要发布一下哦):

3.3.4 field.default.value

         用于设置字段的默认值,支持的版本v1.7.1+。

(1)原生编码支持

         默认的所有含有默认初始值的字段,取其默认初始值. 如:

private short status = -1;

         看了下,只在返回数据有效果,并不是参数:

(2)使用配置:

field.default.value=#default

         然后在注释上进行使用@default:

         看下效果:

         请求参数和返回数据都生效了。

         在运行的界面也是看到是-2:

3.3.4 field.demo

字段示例信息:

field.demo=#demo

         使用:

         效果:

         所以这里可以总结出field.demo配置的是请求参数的示例,field.default.value配置的是返回参数的默认值;当field.demo没有配置的时候会使用field.default.value配置的值。

         其它的配置项大家可以根据文档自行研究。

https://easyyapi.com/setting/rules/field_required.html

结束语

         EasyYapi不仅于此,还有很多需要大家自行进行研究的。正所谓师父领进门,修行靠自身。


购买完整视频,请前往:http://www.mark-to-win.com/TeacherV2.html?id=287