devbox
weixin_40725706
这个屌丝很懒，什么也没留下！
关注作者
热门标签
热门文章
当前位置:   article > 正文

Swagger使用Map接受参数时，页面如何显示具体参数及说

作者：weixin_40725706 | 2024-07-27 12:49:57

赞

踩

Swagger使用Map接受参数时，页面如何显示具体参数及说

Swagger使用Map接受参数时，页面如何显示具体参数及说明

1.需求说明

项目为:SpringBoot+Knife+MyBatisPlus

后端使用Map接受参数，要求在swagger页面上显示具体的参数名称、类型及说明

2.解决方案

1.参数数量少

当Map接受参数数量少时，可以使用Swagger自带的注解 @ApiImplicitParams+@ApiImplicitParam,具体如下：

  1. @GetMapping("/list")
  2. @ApiImplicitParams({
  3.     @ApiImplicitParam(name = "code", value = "字典编号", paramType = "query", dataType = "string"),
  4.     @ApiImplicitParam(name = "dictValue", value = "字典名称", paramType = "query", dataType = "string")
  5. })
  6. @ApiOperationSupport(order = 2)
  7. @ApiOperation(value = "列表", notes = "传入dict")
  8. public R list(@ApiIgnore @RequestParam Map<String, Object> dict) {
  9.   
  10. }
  11.

2.参数数量大且有具体的实体类或DTO

  1. 自定义注解 @ApiGlobalModel

    1. package com.zjjg.dlbp.config.annotation;
    2.  
    3. /**
    4.  * @author 石智铭
    5.  * @Date 2022-10-10
    6.  */
    8. import java.lang.annotation.ElementType;
    9. import java.lang.annotation.Retention;
    10. import java.lang.annotation.RetentionPolicy;
    11. import java.lang.annotation.Target;
    12.  
    13. /**
    14.  * Swagger扩展注解
    15.  * 用于 application/json请求
    16.  * 并使用诸如Map或JSONObject等非具体实体类接收参数时,对参数进行进一步描述
    17.  */
    18. @Target({
    19.         ElementType.METHOD, ElementType.PARAMETER})
    20. @Retention(RetentionPolicy.RUNTIME)
    21. public @interface ApiGlobalModel {
    22.     /**
    23.      * 字段集合容器
    24.      *
    25.      * @return Global model
    26.      */
    27.     Class<?> component();
    28.  
    29.     /**
    30.      * 分隔符
    31.      *
    32.      * @return separator
    33.      */
    34.     String separator() default ",";
    35.  
    36.     /**
    37.      * 实际用到的字段
    38.      * 可以是字符串数组,也可以是一个字符串 多个字段以分隔符隔开: "id,name"
    39.      * 注意这里对应的是component里的属性名,但swagger显示的字段名实际是属性注解上的name
    40.      *
    41.      * @return value
    42.      */
    43.     String[] value() default {
    44.     };
    45. }
    46.

    1. 编写处理注解对应的插件

      1. package com.zjjg.dlbp.config;
      2.  
      3. import cn.hutool.core.util.IdUtil;
      4. import com.fasterxml.classmate.TypeResolver;
      5. import com.zjjg.dlbp.config.annotation.ApiGlobalModel;
      6. import io.swagger.annotations.ApiModelProperty;
      7. import javassist.*;
      8. import javassist.bytecode.AnnotationsAttribute;
      9. import javassist.bytecode.ConstPool;
      10. import javassist.bytecode.annotation.Annotation;
      11. import javassist.bytecode.annotation.StringMemberValue;
      12. import lombok.AllArgsConstructor;
      13. import org.apache.commons.lang3.StringUtils;
      14. import org.slf4j.Logger;
      15. import org.slf4j.LoggerFactory;
      16. import org.springblade.core.tool.utils.Func;
      17. import org.springframework.core.annotation.Order;
      18. import org.springframework.stereotype.Component;
      19. import springfox.documentation.schema.ModelRef;
      20. import springfox.documentation.spi.DocumentationType;
      21. import springfox.documentation.spi.service.ParameterBuilderPlugin;
      22. import springfox.documentation.spi.service.contexts.ParameterContext;
      23.  
      24. import java.util.*;
      25. import java.util.stream.Collectors;
      26.  
      27. /**
      28.  * @author 石智铭
      29.  * @Date 2022-10-10
      30.  * 将map入参匹配到swagger文档中
      31.  * plugin加载顺序，默认是最后加载
      32.  */
      33. @Component
      34. @Order
      35. @AllArgsConstructor
      36. public class ApiGlobalModelBuilder implements ParameterBuilderPlugin {
      37.     private static final Logger logger = LoggerFactory.getLogger(ApiGlobalModelBuilder.class);
      38.  
      39.     private final TypeResolver typeResolver;
      40.  
      41.     @Override
      42.     public void apply(ParameterContext context) {
      43.  
      44.         try {
      45.             // 从方法或参数上获取指定注解的Optional
      46.             Optional<ApiGlobalModel> optional = context.getOperationContext().findAnnotation(ApiGlobalModel.class);
      47.             if (!optional.isPresent()) {
      48.  
      49.                 optional = context.resolvedMethodParameter().findAnnotation(ApiGlobalModel.class);
      50.             }
      51.             if (optional.isPresent()) {
      52.                 Class originClass = context.resolvedMethodParameter().getParameterType().getErasedType();
      53.                 String name = originClass.getSimpleName() + "Model" + IdUtil.objectId();
      54.                 ApiGlobalModel apiAnnotation = optional.get();
      55.                 String[] fields = apiAnnotation.value();
      56.                 String separator = apiAnnotation.separator();
      57.                 ClassPool pool = ClassPool.getDefault();
      58.                 CtClass ctClass = pool.makeClass(name);
      59.                 ctClass.setModifiers(Modifier.PUBLIC);
      60.                 //处理 javassist.NotFoundException
      61.                 pool.insertClassPath(new ClassClassPath(apiAnnotation.component()));
      62.                 CtClass globalCtClass = pool.getCtClass(apiAnnotation.component().getName());
      63.                 // 将生成的Class添加到SwaggerModels
      64.                 context.getDocumentationContext()
      65.                         .getAdditionalModels()
      66.                         .add(typeResolver.resolve(createRefModel(fields,separator,globalCtClass,ctClass)));
      67.                 // 修改Json参数的ModelRef为动态生成的class
      68.                 context.parameterBuilder()
      69.                         .parameterType("body")
      70.                         .modelRef(new ModelRef(name)).name(name).description("body");
      71.             }
      72.         } catch (Exception e) {
      73.           logger.error("@ApiGlobalModel Error",e);
      74.         }
      75.     }
      76.  
      77.  
      78.     @Override
      79.     public boolean supports(DocumentationType delimiter) {
      80.  
      81.         return true;
      82.     }
      83.  
      84.  
      85.     /**
      86.      * 根据fields中的值动态生成含有Swagger注解的javaBeen modelClass
      87.      */
      88.     private Class createRefModel(String[] fieldValues,String separator,CtClass origin,CtClass modelClass) throws NotFoundException, CannotCompileException, ClassNotFoundException {
      89.         List<CtField> allField=getAllFields(origin);
      90.         List<CtField> modelField;
      91.         if (Func.isEmpty(fieldValues)){
      92.             modelField = allField;
      93.         }else {
      94.             List<String> mergeField = merge(fieldValues, separator);
      95.             modelField = allField.stream().filter(e->mergeField.contains(e.getName())).collect(Collectors.toList());
      96.         }
      97.         createCtFields(modelField, modelClass);
      98.         return modelClass.toClass();
      99.     }
      100.  
      101.     public void createCtFields(List<CtField> modelField, CtClass ctClass) throws CannotCompileException, ClassNotFoundException, NotFoundException {
      102.         for (CtField ctField : modelField) {
      103.             CtField field = new CtField(ClassPool.getDefault().get(ctField.getType().getName()), ctField.getName(), ctClass);
      104.             field.setModifiers(Modifier.PUBLIC);
      105.             ApiModelProperty annotation = (ApiModelProperty) ctField.getAnnotation(ApiModelProperty.class);
      106.             String apiModelPropertyValue = java.util.Optional.ofNullable(annotation).map(s -> s.value()).orElse("");
      107.             //添加model属性说明
      108.             if (StringUtils.isNotBlank(apiModelPropertyValue)) {
      109.                 ConstPool constPool = ctClass.getClassFile().getConstPool();
      110.                 AnnotationsAttribute attr = new AnnotationsAttribute(constPool, AnnotationsAttribute.visibleTag);
      111.                 Annotation ann = new Annotation(ApiModelProperty.class.getName(), constPool);
      112.                 ann.addMemberValue("value", new StringMemberValue(apiModelPropertyValue, constPool));
      113.                 attr.addAnnotation(ann);
      114.                 field.getFieldInfo().addAttribute(attr);
      115.             }
      116.             ctClass.addField(field);
      117.         }
      118.     }
      119.  
      120.     /**
      121.      * 获取本类及其父类的字段属性 字段属性去重
      122.      * @param clazz 当前类对象
      123.      * @return 字段数组
      124.      */
      125.     public List<CtField> getAllFields(CtClass clazz) throws NotFoundException {
      126.         List<CtField> fieldList = new ArrayList<>();
      127.         while (clazz != null){
      128.             fieldList.addAll(new ArrayList<>(Arrays.asList(clazz.getDeclaredFields())));
      129.             clazz = clazz.getSuperclass();
      130.         }
      131.  
      132.         return fieldList.stream().collect(Collectors.collectingAndThen(
      133.                 Collectors.toCollection(() -> new TreeSet<CtField>(Comparator.comparing(CtField::getName))), ArrayList::new)
      134.         );
      135.     }
      136.  
      137.     /**
      138.      * 字符串列表 分隔符 合并
      139.      * A{"a","b,c","d"} => B{"a","d","b","c"}
      140.      *
      141.      * @param arr arr
      142.      * @return list
      143.      */
      144.     private List<String> merge(String[] arr, String separator) {
      145.         List<String> tmp = new ArrayList<>();
      146.         Arrays.stream(arr).forEach(s -> {
      147.             if (s.contains(separator)) {
      148.                 tmp.addAll(Arrays.asList(s.split(separator)));
      149.             } else {
      150.                 tmp.add(s);
      151.             }
      152.         });
      153.         return tmp;
      154.     }
      155.  
      156. }
      157.  
      158.
      1. 在具体Controller上添加注解
      1. 	/**
      2. 	 * 修改
      3. 	 */
      4. 	@PostMapping("/update")
      5. 	@ApiOperationSupport(order = 2)
      6. 	@ApiOperation(value = "修改结构物：DLBP-0002-002", notes = "修改结构物：DLBP-0002-002")
      7. 	@ApiGlobalModel(component = SlopeDTO.class)
      8. 	public R update(@RequestBody Map<String,Object> slopeDTO) {
      9. 		return R.status(slopeService.updateSlope(slopeDTO));
      10. 	}
      11.
      1. 存在问题
        1. 无法展示实体类中对象属性或对象集合
声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/weixin_40725706/article/detail/890242
推荐阅读