一篇教你学会SpringBoot集成Swagger3

学习要求

良好的java基础， 熟悉SpringBoot框架，熟悉RESTful接口开发

教学目标

了解并掌握SpringBoot集成Swagger3

环境

springboot2.4.3 + swagger3

集成步骤 SpringBoot集成swagger3个Swagger2 *** 作大部分一样： 传送门：一篇教你学会SpringBoot集成Swagger2

具体区别 依赖

swagger2

	io.springfox
	springfox-swagger2
	2.9.2



	io.springfox
	springfox-swagger-ui
	2.9.2

swagger3

	io.springfox
	springfox-boot-starter
	3.0.0

启动注解

swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
    .....
}

swagger3

@Configuration
@EnableOpenApi
public class SwaggerConfig implements WebMvcConfigurer {
    .....
}

页面地址

swagger2

http://localhost:8080/swagger-ui.html

swagger3

http://localhost:8080/swagger-ui/

最终配置

swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
 
    @Bean
    public Docket productApi() {
 
        //添加head参数start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List pars = new ArrayList();
        //这个位置设置请求头：比如令牌
        tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
 
        return new Docket(DocumentationType.SWAGGER_2).select()
                // 扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.langfeiyes.restful.controller"))
                // 定义要生成文档的Api的url路径规则
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                // 设置swagger-ui.html页面上的一些元素信息。
                .apiInfo(metaData());
    }
 
    private ApiInfo metaData() {
        return new ApiInfoBuilder()
                // 标题
                .title("SpringBoot集成Swagger2")
                // 描述
                .description("xxx项目接口文档")
                // 文档版本
                .version("1.0.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
 
    //ui页面
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

swagger3

@Configuration
@EnableOpenApi
public class SwaggerConfig implements WebMvcConfigurer {
    @Bean
    public Docket productApi() {
        //添加head参数start
        RequestParameterBuilder tokenPar = new RequestParameterBuilder();
        List pars = new ArrayList();
        //这个位置设置请求头：比如令牌
        tokenPar.name("token").description("令牌")
                .in("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2).select()
                // 扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.langfeiyes.restful.controller"))
                // 定义要生成文档的Api的url路径规则
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(pars)
                // 设置swagger-ui.html页面上的一些元素信息。
                .apiInfo(metaData());
    }

    private ApiInfo metaData() {
        return new ApiInfoBuilder()
                // 标题
                .title("SpringBoot集成Swagger2")
                // 描述
                .description("xxx项目接口文档")
                // 文档版本
                .version("1.0.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }

}

常用注解

swagger2与swagger3一致

项目配置拦截器

swagger2

//需要放行的资源
excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui.html/**", "/v2/**");

swagger3

//需要放行的资源
excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui/**", "/v3/**");