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不仅于此，还有很多需要大家自行进行研究的。正所谓师父领进门，修行靠自身。

  1. 我就是我，是颜色不一样的烟火。
  2. 我就是我，是与众不同的小苹果。


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