springboot+swagger3.0

按以下文档操作配置，可避免新版swagger页面无法访问，或者访问出现版本不适配问题。

环境

• JDK1.8
• springboot 2.3.4.RELEASE
• swagger 3.0.0

版本配置

maven

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

配置

swagger初始化配置

package com.xxx.xx.config;

import com.study.spring.constant.KeyConst;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.OperationContext;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spi.service.contexts.SecurityContextBuilder;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

/**
 * 访问地址：http://ip:port/context-path/swagger-ui/index.html
 */
@Slf4j
@EnableOpenApi
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xx.web"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                //.globalRequestParameters(requestParameterList())
                .securityContexts(securityContextList())
                .securitySchemes(securitySchemeList());
    }

    /**
     * API信息
     */
    ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful API")   //文档标题
                .description("rest api")    //文档描述
                //.termsOfServiceUrl("https://www.baidu.com/")  //服务协议
                .contact(contact())
                .version("1.0")
                .build();
    }

    /**
     * 联系人
     */
    Contact contact() {
        return new Contact("xxx", "https://www.jianshu.com/u/57d973544b69", "");
    }


    List<SecurityContext> securityContextList() {
        return Stream.of(new SecurityContextBuilder()
                .securityReferences(securityReferenceList())
                .operationSelector(oper -> selector(oper))
                .build())
                .collect(Collectors.toList());
    }

    boolean selector(OperationContext operationContext) {
        String url = operationContext.requestMappingPattern();
        //这里可以写URL过滤规则
        return true;
    }


    private String SECURITY_SCHEME_TOKEN = KeyConst.TOKEN_HEADER_NAME.toUpperCase();

    List<SecurityReference> securityReferenceList() {
        AuthorizationScope globalScope = new AuthorizationScope("global", "global scope");
        return Stream.of(new SecurityReference.SecurityReferenceBuilder()
                .reference(SECURITY_SCHEME_TOKEN)
                .scopes(new AuthorizationScope[]{globalScope})
                .build())
                .collect(Collectors.toList());
    }

    /**
     * 全局token配置
     */
    List<SecurityScheme> securitySchemeList() {
        return Stream.of(new ApiKey(SECURITY_SCHEME_TOKEN, KeyConst.TOKEN_HEADER_NAME, "header"))
                .collect(Collectors.toList());
    }


    /**
     * 统一设置请求参数
     */
    List<RequestParameter> requestParameterList() {
        RequestParameter headParameter = new RequestParameterBuilder()
                .in(ParameterType.HEADER)
                .name(KeyConst.TOKEN_HEADER_NAME)
                .required(true)
                .build();

        return Stream.of(headParameter).collect(Collectors.toList());
    }

    /**
     * 统一设置HTTP响应状态码及描述信息
     */
    List<Response> responseList() {
        return Stream.of(new ResponseBuilder().code("200").description("OK").build())
                .collect(Collectors.toList());
    }
}

注意

启用swagger注解变化

新版不需要单独增加@EnableSwagger2，只需要添加@EnableOpenApi即可。

只添加@EnableSwagger2会导致页面访问swagger页面404

访问地址变化

新版访问地址为：http://ip:port/context-path/swagger-ui/index.html

自定义拦截器，swagger适配

WebMvcConfigurer子类自定义实现增加

@Override
public void addInterceptors(InterceptorRegistry registry) {
    final String[] patterns = {"/actuator/**", "/error", "/swagger-ui/**", "/swagger-resources/**", "/v2/api-docs"};
    registry.addInterceptor(yourInterceptor()).excludePathPatterns(patterns);
}

自定义拦截器如果不增加swagger信息的过滤，也会导致swagger页面无法访问问题