Java基础之SpringBoot整合knife4j

本文将介绍如何在SpringBoot项目中整合knife4j，以便于更强大的API文档管理和展示。

前置条件

在开始整合之前，需要确保已经具备以下条件：

• 熟悉Java基础知识；
• 熟悉SpringBoot框架；
• 了解Swagger（Swagger是Knife4j的核心依赖）。

整合步骤

1. 引入依赖

在pom.xml文件中加入knife4j和Swagger的依赖：

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

<!--Swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

其中${swagger.version}为Swagger的版本号，版本号可以根据自己的实际情况进行修改。

2. 配置Swagger

在SpringBoot项目中，我们需要添加Swagger的配置类，用于配置Swagger的基本设置。在这里，我们可以通过@Configuration注解来新建一个配置类，如下所示：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //这里需要将com.example.demo.controller替换成自己的Controller所在包名
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档") //文档标题
                .description("SwaggerAPI接口") //文档描述
                .version("1.0") //文档版本号
                .build();
    }
}

在上面的代码中，我们通过@Configuration注解来声明该类是一个配置类，通过@EnableSwagger2注解来启用Swagger，并通过@Bean注解来创建一个Docket对象，用于配置Swagger的基本信息。

其中，apiInfo()方法用于设置Swagger的基本信息，如文档的标题、描述、版本等。docket()方法配置Swagger的生成规则，可以设置生成API的包路径和API基本信息等。在这里，我们将com.example.demo.controller替换成自己Controller所在的包名。

3. 配置Knife4j

在上面的步骤完成后，我们需要把Swagger的UI进行美化，使用Knife4j来实现。

在SpringBoot项目中，我们需要添加Knife4j的配置类，用于配置Knife4j的基本设置。在这里，我们可以通过@Configuration注解来新建一个配置类，如下所示：

@Configuration
public class Knife4jConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //这里需要将com.example.demo.controller替换成自己的Controller所在包名
                .paths(PathSelectors.any())
                .build()
                .groupName("1.0") //API分组名称
                .enable(true)
                .securitySchemes(securitySchemeList())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档") //文档标题
                .description("SwaggerAPI接口") //文档描述
                .version("1.0") //文档版本号
                .build();
    }

    //设置授权信息
    private List<ApiKey> securitySchemeList() {
        List<ApiKey> list = new ArrayList<>();
        list.add(new ApiKey("access_token", "access_token", "header"));
        return list;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> list = new ArrayList<>();
        list.add(SecurityContext.builder()
                .securityReferences(Collections.singletonList(new SecurityReference("access_token", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                .forPaths(PathSelectors.any())
                .build());
        return list;
    }
}

在这里，我们通过@Bean注解来创建一个Docket对象，用于配置Knife4j的基本信息。其中，groupName()方法用于设置API的分组名称，securitySchemeList()方法用于设置授权信息，securityContexts()方法用于设置安全上下文。

4. 启动项目

在上面的步骤完成后，我们需要重新启动SpringBoot项目，访问http://localhost:端口号/doc.html可以看到API的文档页面。

示例

示例1——简单的API文档

假设我们有一个用户信息的API，请求方式为GET，访问路径为/api/user/{id}，返回一个用户的基本信息。我们可以在Controller的方法上面添加@ApiOperation()注解来设置API的详细信息，如下所示：

@RestController
@RequestMapping("/api")
@Api(tags = "用户信息管理")
public class UserController {
    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable("id") Integer id) {
        User user = new User();
        //从数据库中获取用户信息
        return user;
    }
}

在这个例子中，我们通过@ApiOperation()注解来设置API的详细信息，包括API的名称、说明等。在Swagger生成的API文档中，我们可以看到该API的详细信息。

示例2——文件上传API

假设我们有一个文件上传的API，请求方式为POST，访问路径为/api/upload，返回上传成功的文件名和文件路径。我们可以在Controller的方法上面添加@ApiOperation()注解来设置API的详细信息，如下所示：

@RestController
@RequestMapping("/api")
@Api(tags = "文件上传")
public class FileUploadController {
    @ApiOperation(value = "文件上传", notes = "上传单个文件")
    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public Map<String, String> upload(@RequestParam("file") MultipartFile file) {
        Map<String, String> result = new HashMap<>();
        String filename = file.getOriginalFilename();
        String filepath = "D:\\files\\" + filename;
        File destFile = new File(filepath);
        try {
            file.transferTo(destFile);
            result.put("success", "true");
            result.put("filename", filename);
            result.put("filepath", filepath);
        } catch (IOException e) {
            e.printStackTrace();
            result.put("success", "false");
        }
        return result;
    }
}

在这个例子中，我们通过@ApiOperation()注解来设置API的详细信息，包括API的名称、说明、请求方式等。在Swagger生成的API文档中，我们可以看到该API的详细信息，并可以使用UI进行文件上传操作。

小结

通过以上步骤，我们已经成功地将Knife4j整合到SpringBoot项目中，实现了更加美观、易于使用的API文档管理和展示。如果你还没有使用过Knife4j，赶紧试试吧！