让swagger文档支持后台分组校验

回顾前一小节,我们实现了商品模块api定义,通过openApi3文档的定义,直接让swagger生成器帮我们生成API接口和DTO类,对controller做空实现。测试发现swagger在线文档对后台分组校验并未区分的缺陷。本节我们就通过修改springdoc框架的源码来修复这一缺陷。

分组校验文档定义

在我们开发业务模块Rest API时,对于新增和修改操作通常都会采用一个XxxDTO来保存前端提交的数据。而这两种操作在必填校验上有所区分,而其他格式校验都是相同的,很显然我们就可以采用validation框架的分组校验特性,只对字段是否必输(采用@NotNull@NotBlank注解)做分组的区分。

前面我们也介绍了怎么为基于openApi3文档的swagger生成器扩展分组校验的代码生成功能,下面以商品保存为例,看下扩展后的openApi3文档的定义:

yaml 复制代码
# schema定义
components:
  schemas:
    ProductSave:
      description: 商品保存DTO类
      type: object
      x-groups:
        - Add
        - Update
      properties:
        id:
          description: 商品id
          type: integer
          format: int64
          x-validation: "@NotNull(message = MSG_PRODUCT_ID_REQUIRED, groups = Update.class)"
        categoryId:
          description: 三级分类id
          type: integer
          format: int64
          x-validation: "@NotNull(message = MSG_CATEGORY_ID_REQUIRED, groups = Add.class)"
        name:
          description: 商品名称
          type: string
          x-validation: "@NotBlank(message = MSG_PRODUCT_NAME_REQUIRED, groups = Add.class) @Size(min = 4, max = 20, message = MSG_PRODUCT_NAME_RANGE)"
        imgFile:
          description: 图片文件
          type: multipartFile
        detail:
          description: 商品详情
          type: string
          x-validation: "@Size(min = 50, max = 500, message = MSG_PRODUCT_DETAIL_RANGE)"
        price:
          description: 价格
          type: integer
          x-validation: "@NotNull(message = MSG_PRODUCT_PRICE_REQUIRED, groups = Add.class) @Min(value = 1, message = MSG_PRODUCT_PRICE_MIN)"
        stock:
          description: 库存
          type: integer
          x-validation: "@NotNull(message = MSG_PRODUCT_STOCK_REQUIRED, groups = Add.class) @Max(value = 10000, message = MSG_PRODUCT_STOCK_MAX)"

注意这里扩展的分组列表定义:

yaml 复制代码
x-groups:
  - Add
  - Update

列举出所有的分组,字段校验用我们扩展的x-validation来定义,可以通过groups属性来指定针对特定分组的校验,如果不指定则都会被应用。

再看API定义:

yaml 复制代码
  /mall-api/admin/products:
    post:
      tags:
        - productAdmin
      summary: 商品新增
      description: 新增一条商品记录
      operationId: addProduct
      x-group: Add
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ProductSave'
      responses:
        200:
          description: 新增成功
    put:
      tags:
        - productAdmin
      summary: 商品更新
      description: 更新一条商品记录
      operationId: updateProduct
      x-group: Update
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ProductSave'
      responses:
        200:
          description: 更新成功

这里我们用扩展的属性x-group来指定校验要应用的分组。这样通过swagger生成器生成api接口并对controller做空实现后,我们发现swagger在线文档中对输入框的非空校验并没有区分:

这就导致了在线测试会无差别的加非空校验,而无法提交。

修改springdoc源码

从浏览器控制台获取的json文档内容可以看到,这两个api共用了schema:

而该schema会根据后台DTO类字段上加的非空注解将字段整理到一个数组中,并在页面上应用校验规则。

这里我们要做的,就是修改springdoc相关类的源代码,让这两个API不共用schema,而各个使用各自的schema,这样就可以对必输字段进行各自控制了。我们调整下SpringDocAnnotationsUtils.java

java 复制代码
...
public class SpringDocAnnotationsUtils {
    ...
    private static Class<?>[] findValidateGroupClzs(Annotation[] annotations) {
		for (Annotation annotation : annotations) {
			if (annotation instanceof Validated) {
				return ((Validated) annotation).value();
			}
		}
		return null;
	}

	private static String genGroupName(Class<?>[] groupClzs) {
		StringBuilder sb = new StringBuilder();
		for (Class<?> clz : groupClzs) {
			sb.append(clz.getSimpleName());
		}
		return sb.toString();
	}

	private static boolean containsGroup(Class<?>[] sub, Class<?>[] all) {
		for (int i = 0; i < sub.length; i++) {
			if (ArrayUtils.contains(all, sub[i])) {
				return true;
			}
		}
		return false;
	}

	public static Schema extractSchema(Components components, Type returnType, JsonView jsonView, Annotation[] annotations) {
		Schema schemaN = null;
		ResolvedSchema resolvedSchema;
		try {
			resolvedSchema = ModelConverters.getInstance()
					.resolveAsResolvedSchema(
							new AnnotatedType(returnType).resolveAsRef(true).jsonViewAnnotation(jsonView).ctxAnnotations(annotations));
			// 判断参数是否采用了分组
			Class<?>[] validateGroupClzs = findValidateGroupClzs(annotations);
			if (!ObjectUtils.isEmpty(validateGroupClzs)) {

				String groupName = genGroupName(validateGroupClzs);
				String refName = resolvedSchema.schema.get$ref();
				String dtoName = refName.substring(21);
				resolvedSchema.schema.set$ref(refName + "-" + groupName);
				ResolvedSchema rs = new ResolvedSchema();
				rs.schema = resolvedSchema.schema;
				Map<String, Schema> refSchemas = new LinkedHashMap<>(resolvedSchema.referencedSchemas);
				Schema schema;
				refSchemas.put(dtoName + '-' + groupName, schema = refSchemas.get(dtoName));
				refSchemas.remove(dtoName);
				rs.referencedSchemas = refSchemas;
				resolvedSchema = rs;
				// 按照分组判断哪些字段为必传的
				Field[] fields = ((Class) returnType).getDeclaredFields();
				for (Field field : fields) {
					Method method = ((Class) returnType).getDeclaredMethod("get" + StringUtils.capitalize(field.getName()));
					NotNull notNull = AnnotationUtils.findAnnotation(method, NotNull.class);
					NotBlank notBlank = AnnotationUtils.findAnnotation(method, NotBlank.class);
					if (notNull != null && notNull.groups() != null && !containsGroup(validateGroupClzs, notNull.groups())) {
						schema.getRequired().remove(field.getName());
					} else if (notBlank != null && notBlank.groups() != null && !containsGroup(validateGroupClzs, notBlank.groups())) {
						schema.getRequired().remove(field.getName());
					}
				}
			}
		} catch (Exception e) {
			LOGGER.warn(Constants.GRACEFUL_EXCEPTION_OCCURRED, e);
			return null;
		}
		...
	}
    ...
}    

代码调整说明

这里我们基于swagger核心api所处理得到的resolvedSchema,进行了一次搬运,new出一个副本后,把其中的schema以及引用对象搬运过来,对referencedSchemas中map结构的key重新绑定,以分组的名称作为其后缀,并通过新的$ref进行schema的关联。这样就可以对各自的schema中required列表按照参数对象用@Validated修饰的分组信息和字段上校验应用的分组信息进行判断,处理要不要从required列表中移除该字段。

修改后的源码本地重新Install,并在项目中刷新依赖包,这样重新启动服务,访问swagger在线文档,我们将看到schema确实分开了,并且api的测试表单域的非空校验也区分开了:

到此,我们的swagger生成器和springdoc框架源码修改以定制一些扩展功能的尝试基本都结束了,以后我们就可以放心的编写openApi V3的文档,并用生成器生成可较完美的展示在线swagger文档的代码了。这样我们就可以放心的把精力放到业务模块的API设计上了,大家加油!

相关推荐
morris1313 分钟前
【SpringBoot】Xss的常见攻击方式与防御手段
java·spring boot·xss·csp
阿伟*rui3 小时前
配置管理,雪崩问题分析,sentinel的使用
java·spring boot·sentinel
paopaokaka_luck5 小时前
【360】基于springboot的志愿服务管理系统
java·spring boot·后端·spring·毕业设计
Yaml47 小时前
Spring Boot 与 Vue 共筑二手书籍交易卓越平台
java·spring boot·后端·mysql·spring·vue·二手书籍
小小小妮子~7 小时前
Spring Boot详解:从入门到精通
java·spring boot·后端
hong1616887 小时前
Spring Boot中实现多数据源连接和切换的方案
java·spring boot·后端
程序媛小果8 小时前
基于java+SpringBoot+Vue的旅游管理系统设计与实现
java·vue.js·spring boot
AskHarries11 小时前
Spring Boot集成Access DB实现数据导入和解析
java·spring boot·后端
2401_8576226611 小时前
SpringBoot健身房管理:敏捷与自动化
spring boot·后端·自动化
程序员阿龙11 小时前
基于SpringBoot的医疗陪护系统设计与实现(源码+定制+开发)
java·spring boot·后端·医疗陪护管理平台·患者护理服务平台·医疗信息管理系统·患者陪护服务平台