Springboot 整合 knife4j | Swagger文档最简单配置

Posted 2022-12-21 洛阳泰山

项目场景：

    项目场景：这里项目一直用baldex的框架，然后引入的balde封装的swager的包，去配置knife4j接口文档，今天自己建一个一个没有bladex的springboot，去配置knife4j，问题频出，显示报缺少springfox依赖，后来启动打开接口文档网址，老是报/swagger-resources 404的错误，配置WebMvcConfigurer拦截器过滤也不行，后来不断尝试各种办法终于解决了。

---

原因分析：

友情提示

1、目前已经发行的Knife4j版本，Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。另外在网关层聚合(例如gateway)时，必须禁用Knife4j的增强模式

2、使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x

3、微服务聚合组件Knife4jAggregation强势发布，聚合OpenAPI文档太简单了,详见文档

4、Knife4j独立运行版本Knife4jAggregationDesktop强势发布,使用Knife4j渲染OpenAPI文档很简单,详见文档

Java开发使用Knife4j目前有一些不同的版本变化,详见版本说明，主要如下：

1、如果开发者继续使用OpenAPI2的规范结构，底层框架依赖springfox2.10.5版本，那么可以考虑Knife4j的2.x版本

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索2.X最新版本号-->
    <version>2.0.9</version>
</dependency>

2、如果开发者使用OpenAPI3的结构，底层框架依赖springfox3.0.0,可以考虑Knife4j的3.x版本

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.3</version>
</dependency>

 3、如果开发者底层框架使用的是springdoc-openapi框架,则需要使用Knife4j提供的对应版本,需要注意的是该版本没有Knife4j提供的增强功能，是一个纯Ui。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-springdoc-ui</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.3</version>
</dependency>

---

配置教程：

本次示例使用Spring Boot作为脚手架来快速集成Knife4j,Spring Boot版本2.3.5.RELEASE,Knife4j版本2.0.7

第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：

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

第二步：创建Swagger配置依赖，代码如下：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig 

    @Bean
    public Docket moduleDocket()  return docket("网站接口", "com.tarzan.fileprocessing.controller"); 


    private Docket docket(String groupName, String basePackages) 
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(groupName)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackages))
                .paths(PathSelectors.any())
                .build();
    

    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
                .title("泰山文档处理 接口文档系统")
                .description("泰山文档处理 api接口文档系统")
                .license("Powered By Tarzan Liu")
                .licenseUrl("http://127.0.0.1")
                .termsOfServiceUrl("http://127.0.0.1")
                .contact(new Contact("tarzan Liu", "http://127.0.0.1", "[e-mail]"))
                .version("V1.0.0")
                .build();
    

 IndexController.java包含一个简单的RESTful接口,代码示例如下：

@Api(tags = "首页模块")
@RestController
public class IndexController 

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name)
        return ResponseEntity.ok("Hi:"+name);
    

此时，启动Spring Boot工程，在浏览器中访问：http://localhost:8080/doc.html