SpringBoot - 集成SWAGGER的常见问题

SWAGGER2 与 SWAGGER3的区别：

Unable to render this definition

Spring Cloud gateway 在集成SWAGGER容易出现该问题，主要从GATEWAY的访问权限入手进行排查。

访问UI报404

A. 务必务必务必核实POM.XML中的依赖，大部分由于缺少相关依赖造成的。
B. 请求被拦截

// SWAGGER3
@Configuration
public class SwaggerWebConfiguration implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        /** swagger-ui 地址 */
        registry.addResourceHandler("/swagger-ui/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    }
}

// SWAGGER2
@Configuration
public class SwaggerWebConfiguration implements WebMvcConfigurer {
	 @Override
	 protected void addResourceHandlers(ResourceHandlerRegistry registry) {
	   // 解决静态资源无法访问
	   registry.addResourceHandler("/**")
	       .addResourceLocations("classpath:/static/");
	   // 解决SWAGGER无法访问
	   registry.addResourceHandler("/swagger-ui.html")
	       .addResourceLocations("classpath:/META-INF/resources/");
	   // 解决SWAGGER的JS文件无法访问
	   registry.addResourceHandler("/webjars/**")
	       .addResourceLocations("classpath:/META-INF/resources/webjars/");
	 }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

如何添加公共参数？

 @Bean
    public Docket api(SwaggerProperties swaggerProperties) {
        ...
        ApiSelectorBuilder builder = new Docket(DocumentationType.OAS_30)
                .host(swaggerProperties.getHost())
                .apiInfo(apiInfo(swaggerProperties))
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()));

        swaggerProperties.getBasePath().forEach(p -> builder.paths(PathSelectors.ant(p)));
        swaggerProperties.getExcludePath().forEach(p -> builder.paths(PathSelectors.ant(p).negate()));
        return builder.build().globalRequestParameters(getGlobalOperationParameters()).pathMapping("/");

    }
	// 在HEADER中添加公共参数
    private List<RequestParameter> getGlobalOperationParameters() {
        List<RequestParameter> parameters = Arrays.asList(
                new RequestParameterBuilder().name("token").description("令牌").in(ParameterType.HEADER).query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))).build(),
                new RequestParameterBuilder().name("requestId").description("请求ID").in(ParameterType.HEADER).query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))).build(),
                new RequestParameterBuilder().name("Content-Type").description("内容类型").in(ParameterType.HEADER).query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)).defaultValue("application/json")).build()
        );
        return parameters;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

如何根据部署环境自动开启/关闭SWAGGER?

@Profile({"dev", "test"}) // 只有开发和测试环境下SWAGGER才会开启
public class SwaggerAutoConfiguration {
	...
}
1
2
3
4