解决Swagger2返回map复杂结构不能解析的问题

问题描述：

在使用Swagger2进行接口文档生成时，如果返回结果是Map类型并且其中的value为自定义复杂对象时，Swagger2会无法将返回结果正确解析成json格式，从而导致无法正常生成接口文档。

解决方案：

1. 使用Swagger2提供的注解 @ApiOperation(value="接口名称",notes="接口说明") 来标记接口，并在注解中使用 @ApiResponse 来对返回结果进行描述（包括数据结构和类型等信息）。

示例代码：

/**
 * 查询用户信息
 * @param paramMap 入参
 * @return Map类型结果，包含key1和key2两个自定义复杂对象
 */
@ApiOperation(value = "查询用户信息", notes = "查询用户的详细信息，其中包含key1和key2两个自定义复杂对象")
@ApiResponses(value={
        @ApiResponse(code = 200, message = "请求成功",
        response = Map.class, responseContainer="LinkedHashMap",
        examples=@Example({
            @ExampleProperty(value="{\"key1\":{\"prop1\":\"test1\",\"prop2\":2},\"key2\":{\"prop1\":\"test2\",\"prop2\":3}}")
        }))
    }
)
@RequestMapping(value = "/user", method = RequestMethod.GET)
public Map<String, CustomObject> getUserInfo(@RequestParam Map<String, String> paramMap) {
    //TODO: 查询用户信息
    Map<String, CustomObject> userInfoMap = new HashMap<>();
    CustomObject obj1 = new CustomObject("test1", 2);
    CustomObject obj2 = new CustomObject("test2", 3);
    userInfoMap.put("key1", obj1);
    userInfoMap.put("key2", obj2);
    return userInfoMap;
}

1. 在Swagger2配置中启用全局的Json解析器，以支持自定义的复杂对象类型。

示例代码：

@Configuration
@EnableSwagger2
public class Swagger2Config {
  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("user")
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.user"))
        .paths(PathSelectors.any())
        .build()
        .directModelSubstitute(Object.class, java.lang.Void.class) // 解决swagger2的map返回的key为integer的问题
        .useDefaultResponseMessages(false) //禁用默认的响应状态码
        .globalResponses(HttpMethod.GET, defaultResponseMessage()) //设置 GET 方法的全局响应状态码
        .globalResponses(HttpMethod.POST, defaultResponseMessage()) //设置 POST 方法的全局响应状态码
        .globalResponses(HttpMethod.PUT, defaultResponseMessage()) //设置 PUT 方法的全局响应状态码
        .globalResponses(HttpMethod.DELETE, defaultResponseMessage()) //设置 DELETE 方法的全局响应状态码
        .enableUrlTemplating(false) //禁用URL模板功能
        .produces(new HashSet<String>(Arrays.asList("application/json"))) //设置返回类型为 JSON 数据格式
        .consumes(new HashSet<String>(Arrays.asList("application/json"))) //设置接收类型为 JSON 数据格式
        .directModelSubstitute(LocalDateTime.class, String.class) //将LocalDateTime类型转为String类型
        .genericModelSubstitutes(ResponseEntity.class) //将ResponseEntity类型解析成正确的json格式
        .additionalModels(typeResolver.resolve(MyError.class)) //添加Error对象到SwaggerUI中
        .securitySchemes(Arrays.asList(apiKey()))
        .securityContexts(Arrays.asList(securityContext()))
        .directModelSubstitute(Map.class, Object.class) // 全局配置，解决swagger2返回map复杂结构不能解析的问题
        ;
  }
}

以上是解决Swagger2返回Map复杂结构不能解析的问题的完整攻略。