SpringDoc枚举字段处理与SpringBoot接收枚举参数处理

本期内容

  1. 添加SpringDoc配置展示枚举字段,在文档页面中显示枚举值和对应的描述
  2. 添加SpringMVC配置使项目可以接收枚举值,根据枚举值找到对应的枚举

默认内容

先不做任何处理看一下直接使用枚举当做入参是什么效果。

  1. 定义一个枚举
package com.example.enums;import lombok.AllArgsConstructor;
import lombok.Getter;/*** 来源枚举** @author vains*/
@Getter
@AllArgsConstructor
public enum SourceEnum {/*** 1-web网站*/WEB(1, "web网站"),/*** 2-APP应用*/APP(2, "APP应用");/*** 来源代码*/private final Integer value;/*** 来源名称*/private final String source;}
  1. 定义一个入参类
package com.example.model;import com.example.enums.SourceEnum;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;/*** 枚举属性类** @author vains*/
@Data
@Schema(title = "包含枚举属性的类")
public class EnumModel {@Schema(title = "名字")private String name;@Schema(title = "来源")private SourceEnum source;}
  1. 定义一个接口,测试枚举入参的效果
package com.example.controller;import com.example.enums.SourceEnum;
import com.example.model.EnumModel;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** 枚举接口** @author vains*/
@RestController
@RequestMapping("/enum")
@Tag(name = "枚举入参接口", description = "提供以枚举作为入参的接口,展示SpringDoc自定义配置效果")
public class EnumController {@GetMapping("/test01/{source}")@Operation(summary = "url参数枚举", description = "将枚举当做url参数")public SourceEnum test01(@PathVariable SourceEnum source) {return source;}@GetMapping("/test02")@Operation(summary = "查询参数枚举", description = "将枚举当做查询参数")public SourceEnum test02(SourceEnum source) {return source;}@PostMapping(value = "/test03")@Operation(summary = "参数类包含枚举", description = "将枚举当做参数类的属性")public EnumModel test03(@RequestBody EnumModel model) {return model;}}
  1. 启动项目,查看接口文档显示效果

    单个枚举效果
    默认情况下接口显示效果
    作为参数属性显示效果
    枚举作为参数显示效果

文档中默认显示枚举可接收的值是定义的枚举名字(APP,WEB),但是在实际开发中前端会传入枚举对应的值/代码(1,2),根据代码映射到对应的枚举。

解决方案

单个处理方案

枚举入参

详细内容见文档

使用@Parameter注解(方法上/参数前)或者@Parameters注解来指定枚举参数可接受的值。如下所示

例1

@GetMapping("/test01/{source}")
@Parameter(name = "source", schema = @Schema(description = "来源枚举", type = "int32", allowableValues = {"1", "2"}))
@Operation(summary = "url参数枚举", description = "将枚举当做url参数")
public SourceEnum test01(@PathVariable SourceEnum source) {return source;
}

例2

@GetMapping("/test01/{source}")
@Operation(summary = "url参数枚举", description = "将枚举当做url参数")
public SourceEnum test01(@PathVariable@Parameter(name = "source", schema =@Schema(description = "来源枚举", type = "int32", allowableValues = {"1", "2"}))SourceEnum source) {return source;
}

单独枚举入参显示效果

注解标注效果

枚举作为参数类属性

单独处理没有好的办法,像上边添加allowableValues属性只会在原有列表上添加,如下

添加allowableValues属性效果

全局统一处理方案

准备工作

  1. 定义一个统一枚举接口
package com.example.enums;import com.fasterxml.jackson.annotation.JsonValue;import java.io.Serializable;
import java.util.Arrays;
import java.util.Objects;/*** 通用枚举接口** @param <V> 枚举值的类型* @param <E> 子枚举类型* @author vains*/
public interface BasicEnum<V extends Serializable, E extends Enum<E>> {@JsonValueV getValue();/*** 根据子枚举和子枚举对应的入参值找到对应的枚举类型** @param value 子枚举中对应的值* @param clazz 子枚举类型* @param <B>   {@link BasicEnum} 的子类类型* @param <V>   子枚举值的类型* @param <E>   子枚举的类型* @return 返回 {@link BasicEnum} 对应的子类实例*/static <B extends BasicEnum<V, E>, V extends Serializable, E extends Enum<E>> B fromValue(V value, Class<B> clazz) {return Arrays.stream(clazz.getEnumConstants()).filter(e -> Objects.equals(e.getValue(), value)).findFirst().orElse(null);}}

我这里为了通用性将枚举值的类型也设置为泛型类型了,如果不需要可以设置为具体的类型,比如StringInteger等,如果像我这样处理起来会稍微麻烦一些;另外我这里只提供了一个getValue的抽象方法,你也可以再提供一个getNamegetDescription等获取枚举描述字段值的抽象方法。

  1. 让项目中的枚举实现BasicEnum接口并重写getValue方法,如下
package com.example.enums;import lombok.AllArgsConstructor;
import lombok.Getter;/*** 来源枚举** @author vains*/
@Getter
@AllArgsConstructor
public enum SourceEnum implements BasicEnum<Integer, SourceEnum> {/*** 1-web网站*/WEB(1, "web网站"),/*** 2-APP应用*/APP(2, "APP应用");/*** 来源代码*/private final Integer value;/*** 来源名称*/private final String source;}
  1. 定义一个基础自定义接口,提供一些对枚举的操作方法
package com.example.config.basic;import io.swagger.v3.core.util.PrimitiveType;
import io.swagger.v3.oas.models.media.ObjectSchema;
import io.swagger.v3.oas.models.media.Schema;
import org.springframework.beans.BeanUtils;
import org.springframework.util.ReflectionUtils;import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.lang.reflect.Type;
import java.util.Arrays;
import java.util.Comparator;
import java.util.List;
import java.util.Objects;
import java.util.stream.Collectors;/*** 基础自定义接口** @author vains*/
public interface BasicEnumCustomizer {/*** 获取枚举的所有值** @param enumClazz 枚举的class* @return 枚举的所有值*/default List<Object> getValues(Class<?> enumClazz) {return Arrays.stream(enumClazz.getEnumConstants()).filter(Objects::nonNull).map(item -> {// 收集valuesMethod getValue = ReflectionUtils.findMethod(item.getClass(), "getValue");if (getValue != null) {ReflectionUtils.makeAccessible(getValue);return ReflectionUtils.invokeMethod(getValue, item);}return null;}).filter(Objects::nonNull).toList();}/*** 获取值和描述对应的描述信息,值和描述信息以“:”隔开** @param enumClazz 枚举class* @return 描述信息*/default String getDescription(Class<?> enumClazz) {List<Field> fieldList = Arrays.stream(enumClazz.getDeclaredFields()).filter(f -> !Modifier.isStatic(f.getModifiers()))// 排序.sorted(Comparator.comparing(Field::getName).reversed()).toList();fieldList.forEach(ReflectionUtils::makeAccessible);return Arrays.stream(enumClazz.getEnumConstants()).filter(Objects::nonNull).map(item -> fieldList.stream().map(field -> ReflectionUtils.getField(field, item)).map(String::valueOf).collect(Collectors.joining(" : "))).collect(Collectors.joining("; "));}/*** 根据枚举值的类型获取对应的 {@link Schema} 类*  这么做是因为当SpringDoc获取不到属性的具体类型时会自动生成一个string类型的 {@link Schema} ,*  所以需要根据枚举值的类型获取不同的实例,例如 {@link io.swagger.v3.oas.models.media.IntegerSchema}、*  {@link io.swagger.v3.oas.models.media.StringSchema}** @param type         枚举值的类型* @param sourceSchema 从属性中加载的 {@link Schema} 类* @return 获取枚举值类型对应的 {@link Schema} 类*/@SuppressWarnings({"unchecked"})default Schema<Object> getSchemaByType(Type type, Schema<?> sourceSchema) {Schema<Object> schema;PrimitiveType item = PrimitiveType.fromType(type);if (item == null) {schema = new ObjectSchema();} else {schema = item.createProperty();}// 获取schema的type和formatString schemaType = schema.getType();String format = schema.getFormat();// 复制原schema的其它属性BeanUtils.copyProperties(sourceSchema, schema);// 使用根据枚举值类型获取到的schemareturn schema.type(schemaType).format(format);}}

全局自定义内容都是基于org.springdoc.core.customizers包下的一些Customizer接口,SpringDoc在扫描接口信息时会调用这些接口以实现加载使用者的自定义内容,所以这里提供一个基础的Customizer接口。

实现枚举参数自定义

定义一个ApiEnumParameterCustomizer类并实现ParameterCustomizer接口,实现对枚举入参的自定义,同时实现BasicEnumCustomizer接口使用工具方法。

package com.example.config.customizer;import com.example.config.basic.BasicEnumCustomizer;
import com.example.enums.BasicEnum;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.parameters.Parameter;
import org.springdoc.core.customizers.ParameterCustomizer;
import org.springframework.core.MethodParameter;
import org.springframework.stereotype.Component;/*** 枚举参数自定义配置** @author vains*/
@Component
public class ApiEnumParameterCustomizer implements ParameterCustomizer, BasicEnumCustomizer {@Overridepublic Parameter customize(Parameter parameterModel, MethodParameter methodParameter) {Class<?> parameterType = methodParameter.getParameterType();// 枚举处理if (BasicEnum.class.isAssignableFrom(parameterType)) {parameterModel.setDescription(getDescription(parameterType));Schema<Object> schema = new Schema<>();schema.setEnum(getValues(parameterType));parameterModel.setSchema(schema);}return parameterModel;}
}

实现枚举属性的自定义

定义一个ApiEnumPropertyCustomizer类并实现PropertyCustomizer接口,实现对枚举属性的自定义,同时实现BasicEnumCustomizer接口使用工具方法。

package com.example.config.customizer;import com.example.config.basic.BasicEnumCustomizer;
import com.example.enums.BasicEnum;
import com.fasterxml.jackson.databind.type.SimpleType;
import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.oas.models.media.Schema;
import org.springdoc.core.customizers.PropertyCustomizer;
import org.springframework.stereotype.Component;
import org.springframework.util.ObjectUtils;import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;/*** 枚举属性自定义配置** @author vains*/
@Component
public class ApiEnumPropertyCustomizer implements PropertyCustomizer, BasicEnumCustomizer {@Overridepublic Schema<?> customize(Schema property, AnnotatedType type) {// 检查实例并转换if (type.getType() instanceof SimpleType fieldType) {// 获取字段classClass<?> fieldClazz = fieldType.getRawClass();// 是否是枚举if (BasicEnum.class.isAssignableFrom(fieldClazz)) {// 获取父接口if (fieldClazz.getGenericInterfaces()[0] instanceof ParameterizedType parameterizedType) {// 通过父接口获取泛型中枚举值的class类型Type actualTypeArgument = parameterizedType.getActualTypeArguments()[0];Schema<Object> schema = getSchemaByType(actualTypeArgument, property);// 重新设置字段的注释和默认值schema.setEnum(this.getValues(fieldClazz));// 获取字段注释String description = this.getDescription(fieldClazz);// 重置字段注释和标题为从枚举中提取的if (ObjectUtils.isEmpty(property.getTitle())) {schema.setTitle(description);} else {schema.setTitle(property.getTitle() + " (" + description + ")");}if (ObjectUtils.isEmpty(property.getDescription())) {schema.setDescription(description);} else {schema.setDescription(property.getDescription() + " (" + description + ")");}return schema;}}}return property;}}

如果读者不喜欢这样的效果可以自行修改枚举值、描述信息的显示效果

重启项目查看效果

接口1
/test01
接口2
/test02
接口3
/test03

SpringBoot接收枚举入参处理

不知道大家有没有注意到BasicEnum接口中的抽象方法getValue上有一个@JsonValue注解,这个注解会在进行Json序列化时会将该方法返回的值当做当前枚举的值,例如:1/2,如果不加该注解则序列化时会直接变为枚举的名字,例如: APP/WEB。

如果Restful接口入参中有@RequestBody注解则在——统一枚举的getValue方法上有@JsonValue注解的基础上,无需做任何处理,对于Json入参可以这样处理,但是对于POST表单参数或GET查询参数需要添加单独的处理。

定义一个EnumConverterFactory

根据枚举的class类型获取对应的converter,并在converter中直接将枚举值转为对应的枚举
,具体逻辑情况代码中的注释

package com.example.config.converter;import com.example.enums.BasicEnum;
import com.fasterxml.jackson.databind.type.TypeFactory;
import lombok.NonNull;
import org.springframework.core.convert.converter.Converter;
import org.springframework.core.convert.converter.ConverterFactory;
import org.springframework.stereotype.Component;
import org.springframework.util.ReflectionUtils;import java.io.Serializable;
import java.lang.reflect.Method;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.util.function.Function;/*** 处理除 {@link org.springframework.web.bind.annotation.RequestBody } 注解标注之外是枚举的入参** @param <V> 枚举值的类型* @param <E> 枚举的类型* @author vains*/
@Component
public class EnumConverterFactory<V extends Serializable, E extends Enum<E>> implements ConverterFactory<String, BasicEnum<V, E>> {@NonNull@Override@SuppressWarnings("unchecked")public <T extends BasicEnum<V, E>> Converter<String, T> getConverter(Class<T> targetType) {// 获取父接口Type baseInterface = targetType.getGenericInterfaces()[0];if (baseInterface instanceof ParameterizedType parameterizedType&& parameterizedType.getActualTypeArguments().length == 2) {// 获取具体的枚举类型Type targetActualTypeArgument = parameterizedType.getActualTypeArguments()[1];Class<?> targetAawArgument = TypeFactory.defaultInstance().constructType(targetActualTypeArgument).getRawClass();// 判断是否实现自通用枚举if (BasicEnum.class.isAssignableFrom(targetAawArgument)) {// 获取父接口的泛型类型Type valueArgument = parameterizedType.getActualTypeArguments()[0];// 获取值的classClass<V> valueRaw = (Class<V>) TypeFactory.defaultInstance().constructType(valueArgument).getRawClass();String valueOfMethod = "valueOf";// 转换入参的类型Method valueOf = ReflectionUtils.findMethod(valueRaw, valueOfMethod, String.class);if (valueOf != null) {ReflectionUtils.makeAccessible(valueOf);}// 将String类型的值转为枚举值对应的类型Function<String, V> castValue =// 获取不到转换方法时直接返回nullsource -> {if (valueRaw.isInstance(source)) {// String类型直接强转return valueRaw.cast(source);}// 其它包装类型使用valueOf转换return valueOf == null ? null: (V) ReflectionUtils.invokeMethod(valueOf, valueRaw, source);};return source -> BasicEnum.fromValue(castValue.apply(source), targetType);}}return source -> null;}}

定义一个WebmvcConfig配置类,将EnumConverterFactory注册到添加到mvc配置中

package com.example.config;import com.example.config.converter.EnumConverterFactory;
import lombok.AllArgsConstructor;
import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;/*** 添加自定义枚举转换配置** @author vains*/
@AllArgsConstructor
@Configuration(proxyBeanMethods = false)
public class WebmvcConfig implements WebMvcConfigurer {private final EnumConverterFactory<?, ?> enumConverterFactory;@Overridepublic void addFormatters(FormatterRegistry registry) {registry.addConverterFactory(enumConverterFactory);}
}

重启项目并打开在线文档进行测试

枚举入参示例

Gitee地址、Github地址

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

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

相关文章

0基础学习VR全景平台篇第122篇:VR视频剪辑和输出 - PR软件教程

上课&#xff01;全体起立~ 大家好&#xff0c;欢迎观看蛙色官方系列全景摄影课程&#xff01; 开始之前如果没有接触过pr这款软件的话&#xff0c;建议先去看上一篇 认识视频剪辑软件Premiere 大致了解一下pr。 回到正题今天来教大家VR视频的剪辑和输出 我们先双击打开…

喜讯 | 聚铭下一代智慧安全运营中心入选2023年江苏省大数据产业发展试点示范项目

近日&#xff0c;江苏省工信厅公示2023年江苏省大数据产业发展试点示范项目名单。聚铭下一代智慧安全运营中心凭借扎实的技术实力和突出的产品优势成功入选。 为推动新兴数字产业集群建设&#xff0c;夯实大数据产业发展基础&#xff0c;提升产业供给能力和行业赋能效应&…

AD9361寄存器功能笔记之本振频率设定

LO的产生过程如图&#xff1a; 各个模块都有高灵活性。 1、参考时钟即是AD9361全局参考时钟&#xff0c;可以是外接晶振的片上DCXO&#xff0c;或是外部输入的有驱动能力的时钟信号。根据FM-COMMS5的设计&#xff0c;参考时钟可以使用时钟Buffer 40MHz晶振构成的参考频率源。 …

人工智能基础部分21-神经网络中优化器算法的详细介绍,配套详细公式

大家好&#xff0c;我是微学AI&#xff0c;今天给大家介绍一下人工智能基础部分21-神经网络中优化器算法的详细介绍&#xff0c;配套详细公式。本文将介绍几种算法优化器&#xff0c;并展示如何使用PyTorch中的算法优化器&#xff0c;我们将使用MNIST数据集和一个简单的多层感知…

Vue 2使用element ui 表格不显示

直接修改package.json文件 把这两个依赖修改成对应的 删除node_modules 重新安装依赖 重启

VMware Workstation系列:Win11运行VMware延迟卡顿(侧通道缓解相关)

一. Win11运行VMware延迟卡顿 最近在使用VMware时&#xff0c;开机提示如下&#xff1a; 您在运行该虚拟机时启用了侧通道缓解。侧通道缓解可增强安全性&#xff0c;但也会降低性能。 要禁用缓解&#xff0c;请在虚拟机设置的“高级”面板中更改侧通道缓解设置。有关更多详细信…

电巢科技广州科技贸易职业学院高速PCB设计工程师训练营圆满结班!

为深化校企合作&#xff0c;产教融合助力新工科建设&#xff0c;提升学生工程实践能力&#xff0c;电巢工程能力实训班按照不同岗位类别&#xff0c;匹配对应的企业岗位任职能力要求对学生开展分级培养&#xff0c;以产业需求为导向&#xff0c;培养创新型、应用型人才。 11月1…

无法创建 8192 MB 的匿名分页文件: 系统资源不足,无法完成请求的服务。

好久没用VMware Workstation&#xff0c;今天突然要用&#xff0c;发现所有的虚机在启动的时候提示都提示&#xff1a; 无法创建 XXXX MB 的匿名分页文件&#xff1a;页面文件太小&#xff0c;无法完成操作。 未能分配主内存。 模块"MainMem"启动失败。 未能启动…

PDF Reader Pro 3.0.1.0(pdf阅读器)

PDF Reader Pro是一款功能强大的PDF阅读、注释、填写表单&签名、转换、OCR、合并拆分PDF页面、编辑PDF等软件。 它支持多种颜色的高亮、下划线&#xff0c;可以按需选择&#xff0c;没有空白处可以进行注释&#xff0c;这时候便签是你最佳的选择&#xff0c;不点开时自动隐…

全志R128芯片RTOS调试指南

RTOS 调试指南 此文档介绍 FreeRTOS 系统方案支持的常用软件调试方法&#xff0c;帮助相关开发人员快速高效地进行软件调试&#xff0c;提高解决软件问题的效率。 栈回溯 栈回溯是指获取程序的调用链信息&#xff0c;通过栈回溯信息&#xff0c;能帮助开发者快速理清程序执行…

探索实人认证API:保障在线交互安全的关键一步

前言 在数字化时代&#xff0c;随着人们生活的日益数字化&#xff0c;各种在线服务的普及&#xff0c;安全性成为用户体验的至关重要的一环。特别是在金融、电商、社交等领域&#xff0c;确保用户身份的真实性显得尤为重要。而实人认证API作为一种先进的身份验证技术&#xff…

特征工程完整指南 - 第一部分

苏米特班迪帕迪亚 一、说明 特征工程是利用领域知识从原始数据中提取特征的过程。这些功能可用于提高机器学习算法的性能。本篇叙述在特征选择过程的若干数据处理。 一般来说&#xff0c;特征工程有以下子步骤&#xff1a; 特征转换特征构建特征选择特征提取 二、特征转换的缺…

webpack external 详解

作用&#xff1a;打包时将依赖独立出来&#xff0c;在运行时&#xff08;runtime&#xff09;再从外部获取这些扩展依赖&#xff0c;目的时解决打包文件过大的问题。 使用方法&#xff1a; 附上代码块 config.set(externals, {vue: Vue,vue-router: VueRouter,axios: axios,an…

【实战教程】改进YOLOv5与Seg网络结合:实时车道线精准识别系统(含源码及部署步骤)

1.研究的背景 随着自动驾驶技术的不断发展&#xff0c;车道线的实时分割成为了自动驾驶系统中的重要任务之一。车道线的准确分割可以为自动驾驶系统提供重要的环境感知信息&#xff0c;帮助车辆进行准确的路径规划和决策。因此&#xff0c;开发一种高效准确的车道线实时分割系…

markdown常用命令说明,自己常用的,用到其他的再添加

对于要标红的字体 <font color"red">标签中的字会显示为红色</font> 之后的字不会再显示为红色注意: <font color"red">或者<font colorred>或者<font colorred>三种写法都可以

【ARFoundation学习笔记】2D图像检测跟踪

写在前面的话 本系列笔记旨在记录作者在学习Unity中的AR开发过程中需要记录的问题和知识点。主要目的是为了加深记忆。其中难免出现纰漏&#xff0c;更多详细内容请阅读原文以及官方文档。 汪老师博客 文章目录 2D图像检测创建一个图像检测工程图像追踪的禁用和启用多图像追踪…

快来瞧瞧这样制作出来的电子画册,还便于分享宣传呢!

说起电子画册制作&#xff0c;很多人都不知道从何入手。与传统纸质画册相比&#xff0c;电子画册最大的优点是便于传阅&#xff0c;通过微信、QQ等社交平台都能进行转发和分享。而且内容的排版基本上和纸质画册一致&#xff0c;不同的是&#xff0c;无论图片还是文字都可以赋予…

【数据结构算法(二)】链表总结

&#x1f308;键盘敲烂&#xff0c;年薪30万&#x1f308; 目录 普通单向链表 双向链表 带哨兵的链表 环形链表 ⭐双向带头带环链表的实现⭐ ⭐链表基础OJ⭐ 普通单向链表 结点结构&#xff1a;只有val 和 next指针 初始时&#xff1a;head null; 双向链表 指针&…

16.添加脚注footnote

在 LaTeX 中&#xff0c;您可以使用 \footnote 命令来添加脚注&#xff0c;其中包含您想要引用的网址。同时&#xff0c;为了使网址在文本中可点击&#xff0c;您可以使用 hyperref 宏包。 首先&#xff0c;在文档导言部分添加 hyperref 宏包&#xff1a; \usepackage{hyperr…

jvs-智能bi(自助式数据分析)11.21更新功能上线

jvs智能bi更新功能 新增: 1.字段设置节点新增自定义时间格式功能&#xff1b; 自定义功能允许用户根据需要自定义日期和时间字段的显示格式&#xff0c;为用户提供了更大的灵活性和便利性 2.图表时间搜索条件新增向下兼容模式&#xff1b; 时间搜索条件的向下兼容模式允许用…