发布日期: 2023-12-05

Knife4j整合Swagger3

引入架包

<!--knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

配置文件添加

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

定义配置类

/**
 * @EnableOpenApi 开启 Swagger3 的注解。与 Swagger2 启动注解不同 @EnableSwagger2
 * @EnableKnife4j 开启 Knife4j
 * 不需要重写 BeanPostProcessor 类来实现兼容
 */
@Configuration
@EnableOpenApi
@EnableKnife4j
public class SwaggerConfig implements WebMvcConfigurer {

    /**
     * 显示swagger-ui.html文档展示页，还必须注入swagger资源：
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     */
    @Bean(name = "docket")
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            .select()
            //此包路径下的类，才生成接口文档
            .apis(RequestHandlerSelectors.basePackage("com.reach24.xxxx.controller"))
            //加了ApiOperation注解的类，才生成接口文档
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build();
    }

    /**
     * api文档的详细信息函数,注意这里的注解引用的是哪个
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //大标题
            .title("微服务后台服务API接口文档")
            // 版本号
            .version("1.0")
            // 描述
            .description("后台API接口")
            // 作者
            .contact(new Contact("杭州xxxx互联网事业部","www.xxxx.com","xxxx.com"))
            .license("The Apache License, Version 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            .build();
    }
}

不需要重写 BeanPostProcessor 类来实现兼容。

注意

使用 swagger3 需要的架包是：

<!--swagger3-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>${swagger.version}</version>
</dependency>

使用 knife4j 需要的架包是：

<!--knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>