Springboot中整合knife4j接口文档的过程详解

下面是详细讲解“Springboot中整合Knife4j接口文档的过程详解”的完整攻略。

1. 什么是Knife4j

Knife4j是一款基于SpringBoot的开源接口文档生成工具，可以快速生成美观、易读的API文档。与其他文档工具不同的是，Knife4j通过注解来自动生成接口文档，无需手动编写文档说明，大大提高了接口文档的编写效率。

2. 整合Knife4j

2.1 引入依赖

进入Springboot项目的pom.xml文件，在dependencies标签中添加如下依赖：

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

2.2 配置Knife4j

新建Swagger配置类Swagger2Config.java，并在类上添加@EnableSwagger2注解，开启Swagger2配置。

@Configuration
@EnableSwagger2
public class Swagger2Config {

}

然后在Swagger2Config.java中添加如下代码：

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

private ApiInfo getApiInfo() {
    return new ApiInfoBuilder()
            .title("接口文档")
            .description("Springboot整合Knife4j")
            .version("1.0")
            .build();
}

以上代码中，Docket是Swagger的主api配置机制，通过这个类进行配置文档的显示方式、扫描接口的方式等等。getApiInfo()方法则配置了文档的标题、描述和版本等信息。

2.3 注解使用

在Springboot的控制器中添加Swagger的注解即可生成接口文档，例如：

@RestController
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", dataTypeClass = Integer.class)
    @GetMapping("/user/{id}")
    public String getUserInfo(@PathVariable("id") Integer id) {
        return "用户ID：" + id;
    }

}

以上代码中，@ApiOperation注解用于说明接口的作用和功能，@ApiImplicitParam注解则说明了这个接口的参数信息。

2.4 访问接口文档

在项目启动后，访问http://{host}:{port}/doc.html即可打开生成的接口文档页面，例如：http://localhost:8080/doc.html

3. 示例

以下提供两个示例供参考：

3.1 带有请求头的GET请求示例

@RestController
public class HelloController {

    @ApiOperation(value = "say hello", notes = "示例：say hello")
    @ApiImplicitParam(name = "token", value = "token", defaultValue = "123456", required = true, dataTypeClass = String.class, paramType = "header")
    @GetMapping("/hello")
    public String sayHello(@RequestHeader String token) {
        return "Hello！token=" + token;
    }

}

请求头中加入参数token表示认证信息，值为字符串123456。

3.2 POST请求示例

@RestController
public class UserController {

    @ApiOperation(value = "添加用户", notes = "添加新的用户信息")
    @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataTypeClass = User.class)
    @PostMapping("/user")
    public String addUser(@RequestBody User user) {
        return "添加用户成功！" + user.toString();
    }

}

以上示例实现了添加用户的功能，通过RequestBody注解将提交的数据反序列化成User对象，然后进行数据插入操作。

4. 总结

通过以上步骤，我们已经成功的将Knife4j整合到了Springboot项目中，并使用了常见的注解，生成了美观易读的API文档。同时，我们也给出了两个常见的示例，供大家参考和借鉴。