使用Swagger2时遇到的问题

Swagger2使用起来很简单，加一个@EnableSwagger2注解，并引入以下依赖就ok了

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

配置好以后，启动项目，浏览器输入 http://localhost:8080/swagger-ui.html 应该就能看到api页面了。

But…

问题一：认证

Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually:

问题缘由：项目中使用了Spring Security，swagger2相关的资源没作免登陆配置

解决办法：增长以下配置，把Swagger2相关的请求都容许

@Component
public class WebSecurityConfigurer extends WebSecurityConfigurerAdapter {
    @Override
    public void configure(WebSecurity web) throws Exception {
        // allow Swagger URL to be accessed without authentication
        web.ignoring().antMatchers(
                "/swagger-ui.html",
                "/v2/api-docs", // swagger api json
                "/swagger-resources/configuration/ui", // 用来获取支持的动做
                "/swagger-resources", // 用来获取api-docs的URI
                "/swagger-resources/configuration/security", // 安全选项
                "/swagger-resources/**"
        );
    }
}

问题二：页面提示undifined

解决认证问题以后，打开swagger-ui，页面是出来了，不过页面提示

fetching resource list: http://localhost:8080undefined;

api 选择下拉框里面也是undefined，浏览器f12有js报错

Uncaught DOMException: Failed to execute 'open' on 'XMLHttpRequest': Invalid URL
​ at h.end (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:13:5344)
​ at u.execute (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:7:29443)
​ at n.exports.c.execute (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:7:27351)
​ at t.exports.g.build (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:7:17807)
​ at t.exports.g.initialize (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:7:16198)
​ at new t.exports (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:7:14664)
​ at C.n.load (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:13:11513)
​ at C.n.updateSwaggerUi (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:13:11182)
​ at C.n. (http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.min.js:13:10872)
​ at u (http://localhost:8080/webjars/springfox-swagger-ui/lib/backbone-min.js:1:2091)

页面能出来了，至少说明免认证的配置是生效了。

由于swagger的js已经被压缩过，很难从这段js报错发现问题。本想从网上找下源码，无功而返。

不甘心，从网上下载了自定义的ui，稍做整理后，上传到个人github上了

这个自定义的有2个版本，只改了UI，没有改java代码逻辑，
访问地址分别是

• swagger/index.html
• swagger-v2/docs.html

将这2个地址加入过滤，而后方式试了下，结果发现

swagger/index.html 能够正常访问

swagger-v2/docs.html 也有js报错

有错爆出来，又有源码，就好办了。查看了下js报错的位置，是调用了 /v2/api-docs 后处理返回json数据报错了。

直接在浏览器里面访问了下 /v2/api-docs ，发现回来的数据直接是{“error_no”:“0”,“error_info”:“”}

这里应该不对了，返回的怎么会是这个呢？

debug跟踪一下，springfox.documentation.swagger2.web.Swagger2Controller#getDocumentation方法处理完以后，返回的是

return new ResponseEntity<Json>(jsonSerializer.toJson(swagger), HttpStatus.OK);

// 其中JSON对象代码以下
package springfox.documentation.spring.web.json;
import com.fasterxml.jackson.annotation.JsonRawValue;
import com.fasterxml.jackson.annotation.JsonValue;
public class Json {
  private final String value;
  public Json(String value) {
    this.value = value;
  }
  @JsonValue
  @JsonRawValue
  public String value() {
    return value;
  }
}

并且这里的json数据仍是正常的，继续往下执行，发现进入到了项目自定义的ResponseBodyAdvice中。在这个加强器中，对返回的数据都统一加了error_no和error_info。

继续debug发现，这个方法里面把body转成了map，而在转换的时候，获得的是空的map！！？？

那为何明明有数据的body对象，转map就成空的了呢？

// object转map方法核心代码摘录以下
BeanInfo beanInfo = Introspector.getBeanInfo(obj.getClass());
        PropertyDescriptor[] propertyDescriptors = beanInfo.getPropertyDescriptors();
        for (PropertyDescriptor property : propertyDescriptors) {
            String key = property.getName();
            if (StringUtils.equalsIgnoreCase(key, "class")) {
                continue;
            }
            Method getter = property.getReadMethod();
            Object value = getter != null ? getter.invoke(obj) : null;
        }

原来，beanInfo.getPropertyDescriptors()获取属性描述的时候，只能拿到 getXXX,setXXX方法。而上面的Json对象的value字段恰好没有getValue方法。