swagger兼容map入参

灰太狼 2021-01-19 11:09 717阅读 0赞

maven版本号

<dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger2</artifactId>
    	<version>2.7.0</version>
    </dependency>

添加属性类ApiJsonProperty

import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
     
    @Target(ElementType.ANNOTATION_TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    public @interface ApiJsonProperty {
     
    	String key(); // key
     
    	String example() default "";// 示例
     
    	String type() default "string"; // 支持string、int、double
     
    	String description() default "";// 参数描述
     
    	boolean required() default false; // 是否必传
     
    }

添加ApiJsonObject类

import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
     
    @Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
    @Retention(RetentionPolicy.RUNTIME)
    public @interface ApiJsonObject {
     
        ApiJsonProperty[] value(); //对象属性值
        String name();  //对象名称
    }

添加swagger读取自定义信息类MapReaderForApi

import com.fasterxml.classmate.TypeResolver;
    import com.google.common.base.Optional;
     
    import javassist.*;
    import javassist.bytecode.AnnotationsAttribute;
    import javassist.bytecode.ConstPool;
    import javassist.bytecode.annotation.Annotation;
    import javassist.bytecode.annotation.BooleanMemberValue;
    import javassist.bytecode.annotation.DoubleMemberValue;
    import javassist.bytecode.annotation.IntegerMemberValue;
    import javassist.bytecode.annotation.StringMemberValue;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.core.annotation.Order;
    import org.springframework.stereotype.Component;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ResolvedMethodParameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spi.service.ParameterBuilderPlugin;
    import springfox.documentation.spi.service.contexts.ParameterContext;
     
    import java.util.Map;
     
    /**
     * 
     * @Title: MapReaderForApi.java
     * @Description: 将map入参匹配到swagger文档的工具类
     * @version 1.0
     */
    @Component
    @Order // plugin加载顺序，默认是最后加载
    public class MapReaderForApi implements ParameterBuilderPlugin {
    	@Autowired
    	private TypeResolver typeResolver;
     
    	private final static String basePackage = "com.xsy.dto."; // 动态生成的虚拟DTO Class的包路径
     
    	@Override
    	public void apply(ParameterContext parameterContext) {
    		ResolvedMethodParameter methodParameter = parameterContext.resolvedMethodParameter();
     
    		if (methodParameter.getParameterType().canCreateSubtype(Map.class)
    				|| methodParameter.getParameterType().canCreateSubtype(String.class)) { // 判断是否需要修改对象ModelRef,这里我判断的是Map类型和String类型需要重新修改ModelRef对象
    			Optional<ApiJsonObject> optional = methodParameter.findAnnotation(ApiJsonObject.class); // 根据参数上的ApiJsonObject注解中的参数动态生成Class
    			if (optional.isPresent()) {
    				String name = optional.get().name(); // model 名称
    				ApiJsonProperty[] properties = optional.get().value();
     
    				parameterContext.getDocumentationContext().getAdditionalModels()
    						.add(typeResolver.resolve(createRefModel(properties, name))); // 向documentContext的Models中添加我们新生成的Class
     
    				parameterContext.parameterBuilder() // 修改Map参数的ModelRef为我们动态生成的class
    						.parameterType("body").modelRef(new ModelRef(name)).name(name);
    			}
    		}
     
    	}
     
    	/**
    	 * 根据propertys中的值动态生成含有Swagger注解的javaBeen
    	 */
    	private Class createRefModel(ApiJsonProperty[] propertys, String name) {
    		ClassPool pool = ClassPool.getDefault();
    		CtClass ctClass = pool.makeClass(basePackage + name);
     
    		try {
    			for (ApiJsonProperty property : propertys) {
    				ctClass.addField(createField(property, ctClass));
    			}
    			return ctClass.toClass();
    		} catch (Exception e) {
    			e.printStackTrace();
    			return null;
    		}
    	}
     
    	/**
    	 * 根据property的值生成含有swagger apiModelProperty注解的属性
    	 */
    	private CtField createField(ApiJsonProperty property, CtClass ctClass)
    			throws NotFoundException, CannotCompileException {
    		CtField ctField = new CtField(getFieldType(property.type()), property.key(), ctClass);
    		ctField.setModifiers(Modifier.PUBLIC);
     
    		ConstPool constPool = ctClass.getClassFile().getConstPool();
     
    		AnnotationsAttribute attr = new AnnotationsAttribute(constPool, AnnotationsAttribute.visibleTag);
    		Annotation ann = new Annotation("io.swagger.annotations.ApiModelProperty", constPool);
    		ann.addMemberValue("value", new StringMemberValue(property.description(), constPool));
    		// string类型
    		if (ctField.getType().subclassOf(ClassPool.getDefault().get(String.class.getName())))
    			ann.addMemberValue("example", new StringMemberValue(property.example(), constPool));
    		// int类型
    		if (ctField.getType().subclassOf(ClassPool.getDefault().get(Integer.class.getName())))
    			ann.addMemberValue("example", new IntegerMemberValue(Integer.parseInt(property.example()), constPool));
    		// double类型
    		if (ctField.getType().subclassOf(ClassPool.getDefault().get(Double.class.getName())))
    			ann.addMemberValue("example", new DoubleMemberValue(Double.parseDouble(property.example()), constPool));
     
    		ann.addMemberValue("required", new BooleanMemberValue(property.required(), constPool));
     
    		attr.addAnnotation(ann);
    		ctField.getFieldInfo().addAttribute(attr);
     
    		return ctField;
    	}
     
    	/**
    	 * 
    	 * @Title: MapApiReader.java
    	 * @Description: 参数类型，后续可以增加多少类型
    	 * @date 
    	 */
    	private CtClass getFieldType(String type) throws NotFoundException {
    		CtClass fileType = null;
    		switch (type) {
    		case "string":
    			fileType = ClassPool.getDefault().get(String.class.getName());
    			break;
    		case "int":
    			fileType = ClassPool.getDefault().get(Integer.class.getName());
    		case "double":
    			fileType = ClassPool.getDefault().get(Double.class.getName());
    			break;
    		}
    		return fileType;
    	}
     
    	@Override
    	public boolean supports(DocumentationType delimiter) {
    		return true;
    	}
    }

DemoController

@PostMapping(value = "/demo")
    	@ApiOperation(value = "获取资产", notes = "入参为map,userId必传")
    	public String valuationValue(@ApiJsonObject(name = "RequestModel", value = {
    			@ApiJsonProperty(key = "userId", example = "xsy123", description = "用户Id必传", type = "string", required = true),
    			@ApiJsonProperty(key = "indexs", example = "1,2", description = "指标编号非必传", type = "string", required = false),
    			@ApiJsonProperty(key = "queryDate", example = "2018-12-24", description = "查询日期非必传", type = "string", required = false) })
    			@RequestBody Map<String, Object> params) {
    		log.info(String.format("Method[%s], args[%s]", "demo", params.toString()));
    		
    		return "";
    	}

## 最后，注意事项 ##

我们每一个ApiOperation都是按一个RequestMapping来加载的每一个RequestMapping在加载的时候都会经过许多不同类型的Plugin的处理，而负责管理全局的ModelRef的Plugin是OperationModelsProviderPlugin这个处理RequestMapping时会检测有没有还没有被放到全局的ModelRef对象（而我们放到DocumentContext的对象就是此时被加载的），但是OperationModelsProviderPlugin类型的执行顺序是优先于ParameterBuilderPlugin类型的 ，所以这里就有了一个小问题，**如果我们新建的ModelRef是最后一个被处理的RequestMapping那我们新建的ModelRef就没有机会被OperationModelsProviderPlugin放到全局的ModelRef中了，所以解决方法就是在这个Controller中添加一个无用的方法但是这个方法名要足够的长（这个Document范围内即可）保证这个方法才是被SpringFox最后解析的**，让我们每个ModelRef都能被OperationModelsProviderPlugin装载进来，如果想看SpringFox这部分具体实现的可以关注下DocumentationPluginsManager这个类，打个断点（断点在OperationModelsProviderPlugin和ParameterBuilderPlugin这两个plugin的调用地方）应该就能理解了。