学习swagger，使用正则改造项目, 生成接口文档

学习swagger，使用正则改造项目
关于Swagger+Knife4j生成统一接口文档教程请点击以下关于Swagger+Knife4j生成统一接口文档

1 关于构建swagger文档所需要的依赖和配置类

Swagger+Knife4j - 统一接口文档
我们以某一个项目的swagger升级改造为例。

2 如何使用正则表达式改造所有的entity注释为@ApiModelProperty(“架构角色”)

我们都知道经过1后，想要将项目中的每一个entity类都改造为swagger能接受的对象，是费时费力的，如果一个项目有50张表，好5个项目，然后每一张表需要添加@ApiModelPropertity注解的有10多个字段，加一个注解后还需要再将该属性特有的注释复制粘贴一遍，也就说总共最低需要复制粘贴50✖️ 5 ✖️10 * 4 = 2500次 ，而且加上一些其他的controller，model中需要添加swagger注解的部分，其实添加起来是非常麻烦且耗时的，这个时候可以利用idea中的正则表达式进行全局范围内的查找和替换。

因为需要改造的类不仅仅存在于项目的实体关系表中，还可能存在于其他的包的model类中，一般一个包内的所有类都有相似的特征，所以改造的粒度最好是包

注意点：
复制以下的正则表达式的时候一定要主要不要附带旁边的空格也复制了，否则会导致一些缩进的错误。

2.1 entity实体关系表特征分析

通过下面这张图可以明显看出，每一个实现关系类对应一张数据表，其中每一个字段都被统一格式的注释修饰，然后存在主键字段没有注释（需要特殊处理），且类中都被@Data，@TableName注解修饰

2.2 先在目标包内各个需要改造的类中导入swagger的相关类

1 分析：
我们都知道，每一个类都使用到了@Data注解，意味着引入了@Lombok类，所以我们先正则匹配@Lombok，然后再替换

2
（1）正则表达式1： ((import lombok.Data;)(\s+))
替换表达式1：import io.swagger.annotations.*;$3$1
替换前：

替换后：（因为还没有泳道swagger包所以呈现灰色）

上面这个使用了*号来表示引入swagger.annotations下的所有注解，不是很好，那么可以使用下面这种更细粒度的替换方式：

（2）正则2(推荐): ((import lombok.Data;)(\s+))
替换2: import io.swagger.annotations.ApiModel;$3import io.swagger.annotations.ApiModelProperty;$3$1

2.3 在每一个类名前添加@ApiModel注释

1
(1)正则：(@TableName((.*)))(\s+)
(2)替换：$1$3@ApiModel(description = $2)$3
(3)替换效果预览：

(4) 结果：我们发现有一部分替换报错了，点开看一下，发现是原来的部分TableName的值不是按照格式来的，但是好在这样的特例较少，这个时候只需要手动纠正即可

2 (推荐)
正则表达式2：(/*[\s\S]

\s+*\s(.)[\s\S]\n\s{1}*/?(\n))
替换表达式2：$1@ApiModel(“$2”)$3

2.4 为每一个属性添加@ApiModelProperty

1 正则表达式：/**\s\s{5}*\s(.)\s+*?/
2 替换表达式：@ApiModelProperty(“$1”)
这里的$1表示(.)表示注释的内容
3 效果
替换前：

替换后：

2.5 特殊处理主键

1 有的主键属性之前存在注释，有的不存在，所以我们的策略是先使用2.4的正则表达式清除这个包下的所有注释，然后再添加注释（注意2.4必须在2.5前面执行，否则会造成误删）
2 正则： (@TableId(.(\n\s+))
替换：@ApiModelProperty(“主键”)$2$1
说明：$1表示 (@TableId(.(\n\s+)) 代表的内容，$2表示(\n\s+)代表的具体内容
3 替换效果
替换前：

替换后：

3 改造controller包

3.1 分析

要导入的内容有
1 导入swagger依赖包：import io.swagger.annotations.*;
2 修饰在class类上的@Api注解
3 修饰在方法上的@ApiOperation注解

3.2 导入swagger依赖

（1）
正则：(import org.springframework.beans.factory.annotation.Autowired;)(\s+)
替换：import io.swagger.annotations.*;$2$1$2

（2）
正则：(import org.springframework.beans.factory.annotation.Autowired;)(\s+)
替换：import io.swagger.annotations.Api;$2import io.swagger.annotations.ApiOperation;$2$1$2

3.2 在class类上添加@Api注解
分析：可以看到每一个controller类的注释格式总是固定不变的，又因为我们要给@Api加上tags，所以就要以这个注释的内容作为正则表达式的目标对象，在它的下面加上注解

/**
 * 

 * 设备硬件表（部件表） 前端控制器
 * 
 *
 * @author xxxx
 * @since 2020-06-12
 */
1
2
3
4
5
6
7
8

可以看到这里的注释被

标签包围，这是重点，而且只会选择文字的前半段
正则：(\n)((/**\s+*\s

\s+*\s+(\S*)([\s\S]*?)*/)(\s+))
替换：$2@Api(tags = “$4”)$1
效果预览：

3.3 在路由方法上添加@ApiOperation注解

1 找出特征点：所有路由方法都会有一个public Message的开头

2
（1）
正则表达式：((\s+)(public Message))
替换表达式：$2@ApiOperation(value=“”)$1

3.4 为输入参数添加@ApiParam

以下两个表达式都要使用
1
（1）
正则表达式：((@PathVariable)(\s))
替换表达式：$1@ApiParam(“”)$3
（2）
正则表达式： (@RequestParam)
替换表达式：@ApiParam(“”)$1
以上两个分别使用会比较麻烦，现在可以融合一下
2
正则表达式: ((@RequestParam)|(@PathVariable))
替换表达式：@ApiParam(“”)\t$1

3.5 将@RequestBody String input接收方式改为@ApiParam @RequestBody ObjectDTO objectDTO

1 如下：本来的接收前端json字符串的方式是input，然后统一使用JSONTokener解析这个input字符串，这种接收方式优缺点：
当使用swagger接口文档的时候，文档中的输入参数只能显示一个input字段，前端开发人员而无法具体的知道这个input里面的具体的字段。
所以这就需要我们改造input为具体的DTO对象。

2 改造
正则表达式: (String\sinput)
替换表达式:
只需要先把这些符合条件的置空即可（置空后产生的报错不会让我漏掉一些接口），因为具体的DTO对象需要我们根据接口方法自定义。

4 改造Model
如果model包下的类作为controller方法的形参，用于接收前端传过来的数据时，这些被引用的类也需要加上swagger的特殊注解的。
以下有两种方法进行改造
4.1 当model中的类过多，而controller的接口比较少时
可以依据接口逐个查找使用到的model对象

4.2 当controller类中的接口方法过多时
可以利用idea的特性：会显示每一个创建对象的被引用次数以及具体的被哪些方法引用。
比如下面这幅图片，左边精确到一个类的一行语句，右边展示了那行语句的具体代码。直接根据右边的那行代码是不是作为接口的输入参数model即可知道是否要给这个model类加上特定的swagger注解

4.3 如何在model中使用正则
(1) model中应该以类为单位应用正则
(2) 依据各个类中的属性的声明情况写出相应的正则
(3) 属性被private 声明时，
正则表达式：((^(\s{4}).*;$)(\n))
替换表达式：$3@ApiModelProperty(“”)\n$1