SpringBoot集成Swagger3

SpringBoot集成Swagger3

1-添加Swagger3的POM依赖

 
        
            io.springfox
            springfox-boot-starter
            3.0.0
        

2-配置Swagger3配置类

@Configuration
@EnableOpenApi   //swagger3用EnableOpenApi注解 ； swagger2用EnableSwagger2注解
@Profile(value = {"dev","test"})   //表示该配置只在 dev ，test 环境下生效
public class SwaggerCfg {
    @Bean
    public Docket sysCoreApi() {
        //DocumentationType.OAS_30 指的是 openApi 3.0 开放API3.0标准类型
        //Swagger 2与OpenAPI 3 的区别 https://www.jianshu.com/p/879baf1cff07
        // springfox-boot-starter 3.0.0 这个官方提供的swagger推荐使用 OAS_30标准
        // OpenAPI 规范（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，
        // 它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码
        // OpenAPI 规范摘要 https://www.jianshu.com/p/5365ef83252a
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.lte.api"))
                .paths(PathSelectors.any())
                .build().groupName("sys-core")
                .apiInfo(apiInfo())
                //添加登录认证
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

//配置多个Docket可以实现API分组
    @Bean
    public Docket  secondBizApi() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.lte.second.api"))
                .paths(PathSelectors.any())
                .build().groupName("sys-biz")
                .apiInfo(sysBizInfo())
                //添加登录认证
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }




    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("LteAdmin系统核心接口文档")
                .description("LteAdmin")
                .contact(new Contact("liuZh", null, "[email protected]"))
                .version("V1.0")
                .build();
    }

    private ApiInfo sysBizInfo() {
        return new ApiInfoBuilder()
                .title("XX系统业务核心接口文档")
                .description("XXXAdmin")
                .contact(new Contact("liuZh", null, "[email protected]"))
                .version("V1.3")
                .build();
    }

    private List securitySchemes() {
        //设置请求头信息
        List result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }

    private List securityContexts() {
        //设置需要登录认证的路径
        List result = new ArrayList<>();
        result.add(getContextByPath("/lte/.*"));
        return result;
    }

    private SecurityContext getContextByPath(String pathRegex) {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(pathRegex))
                .build();
    }

//设置Swagger3启用JWT的全局认证
    private List defaultAuth() {
        List result = new ArrayList<>();
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        result.add(new SecurityReference("Authorization", authorizationScopes));
        return result;
    }
}

3-访问Swagger3的API文档地址

即访问 http://项目域名:项目端口/servlet-context-path/swagger-ui/

效果图