Springboot+Swagger生成接口文档---自定义返回Model（兼容Map、Object）

最新推荐文章于 2025-01-26 20:59:06 发布

老王的隔壁

最新推荐文章于 2025-01-26 20:59:06 发布

阅读量3.3k

点赞数

CC 4.0 BY-SA版权

分类专栏： spring 文章标签： swagger2

本文链接：https://blog.youkuaiyun.com/alvin_010/article/details/109699326

一、背景

由于项目controller封装的通用返回类不规范，是用继承HashMap实现的，没有使用泛型，导致swagger生成接口文档无法讲返回model自动生成，十分影响和前端对接，@ApiResponses又不支持泛型，于是需要多写点代码兼容.

R类代码片段如下

public class R extends HashMap<String, Object> {
   
   
	private static final long serialVersionUID = 1L;
	public static final int CODE_OK = 0;
	public static final int CODE_ERROR_NEG1 = -1;
	public static final int CODE_ERROR_1 = 1;
	public static final int CODE_ERROR_500 = 500;
	public static final int CODE_WARN = -2;
	public static final String CODE = "code";
	public static final String MSG = "msg";
	public static final String DATA = "data";
	public static final String PAGE = "page";
	public static final String SUCCESS = "success";

	
	public R() {
   
   
		put(CODE, CODE_OK);
		put(MSG, "success");
		put(SUCCESS, true);
	}
	
	public R put(String key, Object value) {
   
   
		super.put(key, value);
		return this;
	}
}

二、实现

前置类、几个注解

@Target({
   
   ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiReturnJson {
   
   
	String key();  //对象名称
    ApiReturnJsonPro[] value(); //对象属性值
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiReturnJsonPro {
   
   
 
    String key();  //key
 
    Class<?> dataType() default String.class;
 
    String description() default "";

	/*
	Page类是自定义的一个分页数据通用返回类，
	*/
    //List Set Page
    String responseContainer() default "";
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiReturnJsonR {
   
   

    Class<?> dataType() default String.class;
 
    String description() default "";

    //List Set Page
    String responseContainer() default "";
}

1、首先需要实现OperationModelsProviderPlugin接口，将我们期望的model添加进documentContext

@Slf4j
@Conditional(DevCondition.class)
@Configuration
@Order(-999)
public class CustomOperationModelsProviderPlugin implements OperationModelsProviderPlugin {
   
   

    @Resource
    private TypeResolver typeResolver;

    private final static String basePackage = "com.xxx.devops.swagger.bean.";

    @Override
    public void apply(RequestMappingContext context) {
   
   
        if (context.getReturnType().isInstanceOf(R.class)) {
   
   
            //生成R类