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

Swagger2文档生成 扩展支持 Map JSONObject 传参_swagger2 jsonobject

作者：黑客灵魂 | 2024-07-29 07:19:39

赞

踩

swagger2 jsonobject

本功能在 Swagger 2.7.0   和   2.9.2 版本 测试通过 ，保证可正常使用，

有问题联系471801687@qq.com

关于Swagger2本身不支持Map/JSONObject传参 生成文档，在网上找了很多，大多是自定义注解，借助第三方插件动态生成类，或者重写Swagger2的多数文件，显得很复杂，而且要看很多代码，跟踪才能了解并修改为自己的，而且还时好时坏，但是这些资料又给我带来了新的灵感。

大体思路，

1、新建一个静态Map,存储自己新建的model变量（不需要创建实体类）

2、自定义注解，实现配置参数信息

3、继承Swagger的部分builder类，根据注解 创建自己的 model 塞入 静态Map

4、添加Swagger Aop切面，将静态Map 合并到 Swagger的model中返回

下面是实现代码 

  1. import com.cloud.utils.util.baseenum.DataType;
  2.  
  3. import java.lang.annotation.ElementType;
  4. import java.lang.annotation.Retention;
  5. import java.lang.annotation.RetentionPolicy;
  6. import java.lang.annotation.Target;
  7.  
  8. /**
  9.  * @author: fengyuan
  10.  * @date 2021-6-3 17:23:28
  11.  * @Description TODO Swagger2配置
  12.  */
  13. @Target(ElementType.ANNOTATION_TYPE)
  14. @Retention(RetentionPolicy.RUNTIME)
  15. public @interface PropFy2 {
  16.  
  17.     String name(); // key
  18.  
  19.     String eg() default "";// 示例
  20.  
  21.     DataType type() default DataType.String; // 支持string、int、double
  22.  
  23.     String desc() default "";// 参数描述
  24.  
  25.     boolean required() default false; // 是否必传
  26.  
  27. }
  1. import com.cloud.utils.util.baseenum.DataType;
  2.  
  3. import java.lang.annotation.ElementType;
  4. import java.lang.annotation.Retention;
  5. import java.lang.annotation.RetentionPolicy;
  6. import java.lang.annotation.Target;
  7.  
  8. /**
  9.  * @author: fengyuan
  10.  * @date 2021-6-3 17:23:28
  11.  * @Description TODO Swagger2配置
  12.  */
  13. @Target(ElementType.ANNOTATION_TYPE)
  14. @Retention(RetentionPolicy.RUNTIME)
  15. public @interface PropFy {
  16.  
  17.     String name(); // key
  18.  
  19.     String eg() default "";// 示例
  20.  
  21.     DataType type() default DataType.String; // 支持string、int、double
  22.  
  23.     String desc() default "";// 参数描述
  24.  
  25.     boolean required() default false; // 是否必传
  26.  
  27.     PropFy2[] map() default {};
  28.  
  29. }
  1. import java.lang.annotation.ElementType;
  2. import java.lang.annotation.Retention;
  3. import java.lang.annotation.RetentionPolicy;
  4. import java.lang.annotation.Target;
  5.  
  6. /**
  7.  * @author: fengyuan
  8.  * @date 2021-6-3 17:23:28
  9.  * @Description TODO Swagger2配置
  10.  */
  11. @Target({ElementType.METHOD})
  12. @Retention(RetentionPolicy.RUNTIME)
  13. public @interface ResObjFY {
  14.  
  15.     PropFy[] value() default {}; //请求属性值
  16.  
  17. }
  1. import java.lang.annotation.ElementType;
  2. import java.lang.annotation.Retention;
  3. import java.lang.annotation.RetentionPolicy;
  4. import java.lang.annotation.Target;
  5.  
  6. /**
  7.  * @author: fengyuan
  8.  * @date 2021-6-3 17:23:28
  9.  * @Description TODO Swagger2配置
  10.  */
  11. @Target({ElementType.PARAMETER})
  12. @Retention(RetentionPolicy.RUNTIME)
  13. public @interface ReqObjFy {
  14.  
  15.     PropFy[] value(); //对象属性值
  16.  
  17. }
  1. //随便找个地方
  2. public static Map<String, Model> modelMap = new HashMap<>();
  1. //此为创建Model的方法，深度支持2级
  2. import com.cloud.utils.util.baseenum.DataType;
  3. import com.cloud.utils.utilabstract.BasePubFun;
  4. import io.swagger.models.ModelImpl;
  5. import io.swagger.models.properties.*;
  6. import org.apache.commons.lang3.StringUtils;
  7.  
  8. import java.util.LinkedHashMap;
  9. import java.util.Map;
  10.  
  11. /**
  12.  * @author: fengyuan
  13.  * @date 2021-6-3 15:17:49
  14.  * @Description TODO Swagger2配置公共方法
  15.  */
  16. public class SwaggerFun {
  17.  
  18.     public static String createModelRst(String name, PropFy[] pros) {
  19.  
  20.         createModel(name, pros);
  21.  
  22.         Map<String, Property> proMap = new LinkedHashMap<>();
  23.  
  24.         Property code = new StringProperty();
  25.         code.setName("code");
  26.         code.setDescription("状态'10000'成功，其他失败");
  27.         code.setExample((Object) "10000");
  28.         proMap.put("code", code);
  29.  
  30.         Property msg = new StringProperty();
  31.         msg.setName("msg");
  32.         msg.setDescription("提示");
  33.         proMap.put("msg", msg);
  34.  
  35.         Property msgext = new StringProperty();
  36.         msgext.setName("msgext");
  37.         msgext.setDescription("详情");
  38.         proMap.put("msgext", msgext);
  39.  
  40.         Property result = new RefProperty(name);
  41.         result.setName("result");
  42.         result.setDescription("结果集");
  43.         proMap.put("result", result);
  44.  
  45.         Property success = new BooleanProperty();
  46.         success.setName("success");
  47.         success.setDescription("状态 true成功 false失败");
  48.         proMap.put("success", success);
  49.  
  50.         //创建model
  51.         String rstName = BasePubFun.format("RstData<{}>", name);
  52.         ModelImpl model = new ModelImpl();
  53.         model.setName(rstName);
  54.         model.setProperties(proMap);
  55.         model.setType("object");
  56.         SwaggerFy.modelMap.put(rstName, model);
  57.         return model.getName();
  58.     }
  59.  
  60.     public static void createModel(String name, PropFy[] pros) {
  61.  
  62.         Map<String, Property> proMap = new LinkedHashMap<>();
  63.         for (PropFy pro : pros) {
  64.             Property property = null;
  65.             try {
  66.                 if (DataType.String.equals(pro.type())) {
  67.                     property = new StringProperty();
  68.                     property.setExample(StringUtils.isBlank(pro.eg()) ? "" : (Object) pro.eg());
  69.                 } else if (DataType.Long.equals(pro.type())) {
  70.                     property = new LongProperty();
  71.                     property.setExample(StringUtils.isBlank(pro.eg()) ? 0L : Long.valueOf(pro.eg()));
  72.                 } else if (DataType.Integer.equals(pro.type())) {
  73.                     property = new IntegerProperty();
  74.                     property.setExample(StringUtils.isBlank(pro.eg()) ? 0 : Integer.valueOf(pro.eg()));
  75.                 } else if (DataType.Date.equals(pro.type())) {
  76.                     property = new DateProperty();
  77.                     property.setExample(StringUtils.isBlank(pro.eg()) ? "" : Boolean.valueOf(pro.eg()));
  78.                 } else if (DataType.Boolean.equals(pro.type())) {
  79.                     property = new BooleanProperty();
  80.                     property.setExample(StringUtils.isBlank(pro.eg()) ? "" : Boolean.valueOf(pro.eg()));
  81.                 } else if (DataType.Map.equals(pro.type())) {
  82.                     String tempName = name + "_" + pro.name();
  83.                     createModel(tempName, pro.map());
  84.                     property = new RefProperty(tempName);
  85.                 } else {
  86.                     property = new StringProperty();
  87.                     property.setExample((Object) pro.eg());
  88.                 }
  89.             } catch (Exception e) {
  90.             }
  91.             property.setDescription(pro.desc());
  92.             property.setRequired(pro.required());
  93.             property.setName(pro.name());
  94.             proMap.put(pro.name(), property);
  95.         }
  96.         ModelImpl model = new ModelImpl();
  97.         model.setName(name);
  98.         model.setProperties(proMap);
  99.         model.setType("object");
  100.         SwaggerFy.modelMap.put(name, model);
  101.     }
  102.  
  103.     private static void createModel(String name, PropFy2[] pros) {
  104.         Map<String, Property> proMap = new LinkedHashMap<>();
  105.         for (PropFy2 pro : pros) {
  106.             Property property = null;
  107.             if (DataType.String.equals(pro.type())) {
  108.                 property = new StringProperty();
  109.                 property.setExample(StringUtils.isBlank(pro.eg()) ? "" : (Object) pro.eg());
  110.             } else if (DataType.Long.equals(pro.type())) {
  111.                 property = new LongProperty();
  112.                 property.setExample(StringUtils.isBlank(pro.eg()) ? 0L : Long.valueOf(pro.eg()));
  113.             } else if (DataType.Integer.equals(pro.type())) {
  114.                 property = new IntegerProperty();
  115.                 property.setExample(StringUtils.isBlank(pro.eg()) ? 0 : Integer.valueOf(pro.eg()));
  116.             } else if (DataType.Date.equals(pro.type())) {
  117.                 property = new DateProperty();
  118.                 property.setExample(StringUtils.isBlank(pro.eg()) ? "" : Boolean.valueOf(pro.eg()));
  119.             } else if (DataType.Boolean.equals(pro.type())) {
  120.                 property = new BooleanProperty();
  121.                 property.setExample(!StringUtils.isBlank(pro.eg()) && Boolean.valueOf(pro.eg()));
  122.             }
  123.             property.setDescription(pro.desc());
  124.             property.setRequired(pro.required());
  125.             property.setName(pro.name());
  126.             proMap.put(pro.name(), property);
  127.         }
  128.         ModelImpl model = new ModelImpl();
  129.         model.setName(name);
  130.         model.setProperties(proMap);
  131.         model.setType("object");
  132.         SwaggerFy.modelMap.put(name, model);
  133.     }
  134.  
  135. }
  1. import com.alibaba.fastjson.JSONObject;
  2. import com.google.common.base.Optional;
  3. import org.springframework.core.annotation.Order;
  4. import org.springframework.stereotype.Component;
  5. import springfox.documentation.schema.ModelRef;
  6. import springfox.documentation.service.ResolvedMethodParameter;
  7. import springfox.documentation.spi.DocumentationType;
  8. import springfox.documentation.spi.service.ParameterBuilderPlugin;
  9. import springfox.documentation.spi.service.contexts.ParameterContext;
  10.  
  11. import java.util.Map;
  12.  
  13. /**
  14.  * @author: fengyuan
  15.  * @date 2021-6-3 15:17:49
  16.  * @Description TODO Swagger2配置
  17.  */
  18. @Component
  19. @Order // plugin加载顺序，默认是最后加载
  20. public class ParamReqPlugin implements ParameterBuilderPlugin {
  21.  
  22.     @Override
  23.     public void apply(ParameterContext parameterContext) {
  24.         ResolvedMethodParameter methodParameter = parameterContext.resolvedMethodParameter();
  25.         // 判断是否需要修改对象ModelRef,这里我判断的是Map类型和JSONObject类型需要重新修改ModelRef对象
  26.         if (!methodParameter.getParameterType().canCreateSubtype(Map.class) && methodParameter.getParameterType().canCreateSubtype(JSONObject.class)) {
  27.             return;
  28.         }
  29.         Optional<ReqObjFy> optional = methodParameter.findAnnotation(ReqObjFy.class);
  30.         if (!optional.isPresent()) {
  31.             return;
  32.         }
  33.         String name = parameterContext.getOperationContext().requestMappingPattern().replace("/", "_").substring(1);
  34.         SwaggerFun.createModel(name, optional.get().value());
  35.         parameterContext.parameterBuilder().parameterType("body").modelRef(new ModelRef(name)).name(name);
  36.     }
  37.  
  38.     @Override
  39.     public boolean supports(DocumentationType delimiter) {
  40.         return true;
  41.     }
  42.  
  43. }
  1. import com.cloud.utils.dto.RstData;
  2. import com.fasterxml.classmate.ResolvedType;
  3. import com.google.common.base.Optional;
  4. import org.springframework.core.annotation.Order;
  5. import org.springframework.stereotype.Component;
  6. import springfox.documentation.builders.ResponseMessageBuilder;
  7. import springfox.documentation.schema.ModelRef;
  8. import springfox.documentation.service.ResponseMessage;
  9. import springfox.documentation.spi.DocumentationType;
  10. import springfox.documentation.spi.service.OperationBuilderPlugin;
  11. import springfox.documentation.spi.service.contexts.OperationContext;
  12.  
  13. import java.util.HashSet;
  14.  
  15. /**
  16.  * @author: fengyuan
  17.  * @date 2021-6-3 15:17:49
  18.  * @Description TODO Swagger2配置
  19.  */
  20. @Component
  21. @Order // plugin加载顺序，默认是最后加载
  22. public class ParamResPlugin implements OperationBuilderPlugin {
  23.  
  24.     @Override
  25.     public void apply(OperationContext operationContext) {
  26.         ResolvedType returnType = operationContext.getReturnType();
  27.         // 判断是否需要修改对象ModelRef,这里我判断的是RstData类型需要重新修改ModelRef对象
  28.         if (!returnType.canCreateSubtype(RstData.class)) {
  29.             return;
  30.         }
  31.         Optional<ResObjFY> optional = operationContext.findAnnotation(ResObjFY.class);
  32.         if (!optional.isPresent()) {
  33.             return;
  34.         }
  35.         String name = operationContext.requestMappingPattern().replace("/", "_").substring(1) + "_rst";
  36.         String rstName = SwaggerFun.createModelRst(name, optional.get().value());
  37.         ResponseMessage responseMessage = new ResponseMessageBuilder()
  38.                 .code(200).responseModel(new ModelRef(rstName))
  39.                 .build();
  40.         HashSet<ResponseMessage> responseMessages = new HashSet<>();
  41.         responseMessages.add(responseMessage);
  42.         operationContext.operationBuilder().responseMessages(responseMessages);
  43.     }
  44.  
  45.     @Override
  46.     public boolean supports(DocumentationType delimiter) {
  47.         return true;
  48.     }
  49. }
  50.  
  1. import io.swagger.models.Swagger;
  2. import org.aspectj.lang.ProceedingJoinPoint;
  3. import org.aspectj.lang.annotation.Around;
  4. import org.aspectj.lang.annotation.Aspect;
  5. import org.aspectj.lang.annotation.Pointcut;
  6. import org.springframework.stereotype.Component;
  7.  
  8. /**
  9.  * @author: fengyuan
  10.  * @date 2021-6-3 17:23:28
  11.  * @Description TODO Swagger2配置
  12.  */
  13. @Aspect
  14. @Component
  15. public class SwaggerAop {
  16.  
  17.     @Pointcut(value = "execution(public * springfox.documentation.swagger2.mappers.ServiceModelToSwagger2MapperImpl.mapDocumentation(..))")
  18.     public void point() {
  19.     }
  20.  
  21.     @Around("point()")
  22.     public Object around(ProceedingJoinPoint proceedingJoinPoint) throws Throwable {
  23.         Swagger swagger = (Swagger) proceedingJoinPoint.proceed();
  24.         swagger.getDefinitions().putAll(SwaggerFy.modelMap);
  25.         return swagger;
  26.     }
  27.  
  28. }
  1. @PostMapping(value = "demo")
  2. @ApiOperation("请求参数配置方式，支持二级")
  3. @ResObjFY({
  4.         @PropFy(name = "id", eg = "123", desc = "主键", type = DataType.Long, required = true),
  5.         @PropFy(name = "row", desc = "具体数据", type = DataType.Map, map = {
  6.                 @PropFy2(name = "idCard", eg = "610126198911111111", desc = "身份证号", type = DataType.String, required = true),
  7.                 @PropFy2(name = "name", eg = "张三", desc = "姓名", required = true),
  8.                 @PropFy2(name = "sex", eg = "1", desc = "性别 1男 2女", type = DataType.Integer),
  9.         })
  10. })
  11. public RstData demo(
  12.         @ReqObjFy({
  13.                 @PropFy(name = "id", eg = "123", desc = "主键", type = DataType.Long, required = true),
  14.                 @PropFy(name = "row", desc = "具体数据", type = DataType.Map, map = {
  15.                         @PropFy2(name = "idCard", eg = "610126198911111111", desc = "身份证号", type = DataType.String, required = true),
  16.                         @PropFy2(name = "name", eg = "张三", desc = "姓名", required = true),
  17.                         @PropFy2(name = "sex", eg = "1", desc = "性别 1男 2女", type = DataType.Integer),
  18.                 })
  19.         })
  20.         @RequestBody Map<String, Object> params) {
  21.     return RstData.success(params);
  22. }

效果图 

2.7.0

2.9.2

下面为Swagger扩展Ui的依赖及效果图
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/黑客灵魂/article/detail/897710
推荐阅读
相关标签

Copyright © 2003-2013 www.wpsshop.cn 版权所有，并保留所有权利。

  

闽ICP备14008679号