Swagger2 关于Map参数在API文档中展示详细参数以及参数说明_swagger map参数

前言

本文主要解决的问题是 Swagger2 （SpringFox）关于Map参数生成的API文档中没有详细Json结构说明，问题如下图所示：

此种方式生成的Api文档中的请求参数如下:

如果是这样的参数类型的会让查看API的人员无法清晰的知道如何请求API文档。当然Swagger2 根据这种情况也给出了解决方案：

 
    @ApiOperation(value = "not use")
    @ApiImplicitParam(name = "params" , paramType = "body",examples = @Example({
        @ExampleProperty(value = "{'user':'id'}", mediaType = "application/json")
    }))
    @PostMapping("/xxx")
    public void test(Map<String,String> params){}

但是这种写法在SpringFox版本2.8.0至2.9.0之间好像没有实现@ApiImplicitParam的examples的用法，还是属于issue的状态，下面是关于这两个issue的说明：

http://springfox.github.io/springfox/docs/current/#changing-how-generic-types-are-named

https://stackoverflow.com/questions/41861164/how-can-i-manually-describe-an-example-input-for-a-java-requestbody-mapstring

解决方法

SpringFox 提供给我们了一个ParameterBuilderPlugin接口，通过这个接口我们可以在SpringFox构造Map参数映射的ModelRef时使用javassist动态的生成类，并把这个map参数的modelRef对象指向我们动态生成的具体Class对象（通过自定义注解在Map参数上生成可表示JSON结构的类），具体实现如下(求方便的同学可以把下面3个类直接Copy到自己的代码中即可)：

package com.telepay.service.controller.agent;
 
import com.fasterxml.classmate.TypeResolver;
import com.google.common.base.Optional;
import com.telepay.service.controller.agent.annotation.ApiJsonObject;
import com.telepay.service.controller.agent.annotation.ApiJsonProperty;
import javassist.*;
import javassist.bytecode.