SpringBoot怎么集成Swagger3与Knife4j

在现代的Web开发中，API文档的生成和管理是一个非常重要的环节。Swagger是一个流行的API文档生成工具，而Knife4j是Swagger的增强版，提供了更加丰富的功能和更好的用户体验。本文将详细介绍如何在SpringBoot项目中集成Swagger3与Knife4j，并生成美观、易用的API文档。

1. 什么是Swagger和Knife4j

1.1 Swagger

Swagger是一个用于生成、描述、调用和可视化RESTful风格的Web服务的开源框架。它通过注解的方式自动生成API文档，并提供交互式的API测试界面。Swagger的核心组件包括：

• Swagger Core：用于生成API文档的核心库。
• Swagger UI：一个可视化的API文档界面，允许用户直接在浏览器中测试API。
• Swagger Codegen：根据API文档生成客户端代码的工具。

1.2 Knife4j

Knife4j是Swagger的增强版，基于Swagger2和Swagger3进行了扩展和优化。Knife4j提供了更加丰富的功能，包括：

• 增强的UI界面：Knife4j的UI界面更加美观，支持多语言、多主题切换。
• 离线文档导出：支持将API文档导出为Markdown、HTML、PDF等格式。
• API调试：提供了更加便捷的API调试功能，支持请求参数自动填充、响应结果格式化等。
• 权限控制：支持对API文档的访问权限进行控制。

2. SpringBoot集成Swagger3

2.1 添加依赖

首先，我们需要在SpringBoot项目中添加Swagger3的依赖。在pom.xml文件中添加以下依赖：

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

2.2 配置Swagger

接下来，我们需要配置Swagger。在SpringBoot项目中，可以通过创建一个配置类来配置Swagger。以下是一个简单的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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成Swagger3示例")
                .description("这是一个简单的SpringBoot集成Swagger3的示例")
                .version("1.0")
                .build();
    }
}

在这个配置类中，我们创建了一个Docket Bean，用于配置Swagger的基本信息。apiInfo()方法用于设置API文档的基本信息，如标题、描述、版本等。apis()方法用于指定生成API文档的Controller包路径，paths()方法用于指定生成API文档的URL路径。

2.3 使用Swagger注解

在Controller类中，我们可以使用Swagger的注解来描述API接口。以下是一个简单的Controller示例：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Api(tags = "示例API")
public class ExampleController {

    @GetMapping("/hello")
    @ApiOperation(value = "获取Hello信息", notes = "这是一个简单的获取Hello信息的API")
    public String hello() {
        return "Hello, Swagger3!";
    }
}

在这个Controller中，我们使用了@Api注解来描述整个Controller的功能，使用@ApiOperation注解来描述具体的API接口。

2.4 访问Swagger UI

启动SpringBoot项目后，我们可以通过访问http://localhost:8080/swagger-ui.html来查看生成的API文档。Swagger UI界面提供了交互式的API测试功能，用户可以直接在浏览器中测试API。

3. SpringBoot集成Knife4j

3.1 添加依赖

为了集成Knife4j，我们需要在pom.xml文件中添加Knife4j的依赖：

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

3.2 配置Knife4j

Knife4j的配置与Swagger类似，我们可以在Swagger配置类的基础上进行扩展。以下是一个简单的Knife4j配置类示例：

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成Knife4j示例")
                .description("这是一个简单的SpringBoot集成Knife4j的示例")
                .version("1.0")
                .build();
    }
}

3.3 访问Knife4j UI

启动SpringBoot项目后，我们可以通过访问http://localhost:8080/doc.html来查看Knife4j生成的API文档。Knife4j的UI界面比Swagger UI更加美观，功能也更加丰富。

4. Knife4j的高级功能

4.1 离线文档导出

Knife4j支持将API文档导出为多种格式，包括Markdown、HTML、PDF等。用户可以在Knife4j的UI界面中点击“导出”按钮，选择导出格式并下载文档。

4.2 API调试

Knife4j提供了更加便捷的API调试功能。用户可以在Knife4j的UI界面中直接填写请求参数，并查看响应结果。Knife4j还支持请求参数自动填充、响应结果格式化等功能。

4.3 权限控制

Knife4j支持对API文档的访问权限进行控制。用户可以通过配置Spring Security或其他权限控制框架，限制只有授权用户才能访问API文档。

5. 总结

本文详细介绍了如何在SpringBoot项目中集成Swagger3与Knife4j，并生成美观、易用的API文档。通过集成Swagger3，我们可以自动生成API文档，并通过Swagger UI进行交互式测试。通过集成Knife4j，我们可以获得更加丰富的功能和更好的用户体验。希望本文能够帮助读者更好地理解和使用Swagger3与Knife4j，提升API文档的生成和管理效率。