SpringBoot Knife4j在线API文档框架基本使用

下面是SpringBoot Knife4j在线API文档框架基本使用的完整攻略。

1. Knife4j简介

Knife4j是SpringBoot的开源在线API文档管理框架，它基于Swagger实现，可以让Java开发者非常方便地管理和维护API文档，同时也提供了友好的UI界面，使得API文档的查看更加直观。同时，Knife4j部署简单、使用方便，非常适合在团队协作和对接中广泛使用。

2. Knife4j框架基本使用

2.1 添加Knife4j依赖

首先，在SpringBoot项目中添加Knife4j依赖：

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

2.2 配置Knife4j

在SpringBoot项目中添加Knife4j配置类

@Configuration
@EnableSwagger2
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        //文档说明信息
        return new ApiInfoBuilder()
                .title("SpringBoot Knife4j API接口文档")
                .description("更多相关信息请关注：https://www.xxx.com")
                .termsOfServiceUrl("https://www.xxx.com")
                .contact(new Contact("作者", "https://www.xxx.com", "[e-mail]"))
                .version("1.0")
                .build();
    }

}

配置类中包含了Swagger相关的一些配置信息，如apiInfo来指定文档的标题、描述、版本等。而defaultApi2就是我们的API文档集合，添加到其中的每一个接口方法都将生成一个API文档。

2.3 扫描生成API文档

在启动类上加上注解@EnableKnife4j，并加上扫描 com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j，表示启用Knife4j：

@SpringBootApplication
@EnableKnife4j
@MapperScan("com.xxx.xxx")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

2.4 查看生成的API文档

以上的配置完成后，重新启动SpringBoot项目，访问"http://${host}:${port}/doc.html"即可打开Knife4j的API文档管理界面。

3. 示例

下面通过两条示例来了解Knife4j框架的使用。

示例一：添加接口文档说明

假设现在有一个UserController，其中有一个getUserById的接口，可以通过id获取用户信息。我们可以在接口上添加@Api注解来对接口进行说明：

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理相关接口")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户信息", notes = "根据id获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "String", paramType = "path")
    public UserVo getUserById(@PathVariable String id) {
        return userService.getUserById(id);
    }

}

在@Api注解中，我们可以设置tags、value来对接口进行说明，在@ApiOperation中，我们可以设置value、notes来对接口进行简单明了的说明，而@ApiImplicitParam则可以对接口的参数进行说明。

示例二：快捷添加API文档

在我们的API项目中，接口较多，一个一个添加显然比较麻烦。这时，我们可以通过注解@ApiIgnore来排除不需要生成API文档的接口，然后通过@ApiModel、@ApiModelProperty注解来快速自动生成API文档：

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理相关接口")
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * 添加用户接口
     * @param user
     * @return
     */
    @PostMapping("")
    @ApiOperation(value = "添加用户接口")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "UserCreateReq", paramType = "body")
    })
    public ResponseEntity<UserVo> addUser(@RequestBody UserCreateReq user) {
        return ResponseEntity.ok(userService.addUser(user));
    }

    /**
     * 更新用户信息接口
     * @param id
     * @param userReq
     * @return
     */
    @PutMapping("/{id}")
    @ApiOperation(value = "更新用户信息接口")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "String", paramType = "path"),
        @ApiImplicitParam(name = "userReq", value = "用户信息", required = true, dataType = "UserUpdateReq", paramType = "body")
    })
    public ResponseEntity<UserVo> updateUser(@PathVariable String id, @RequestBody UserUpdateReq userReq) {
        return ResponseEntity.ok(userService.updateUser(id, userReq));
    }

    //忽略不需要生成API文档的接口
    @ApiIgnore
    @DeleteMapping("/{id}")
    public void deleteUserById(@PathVariable String id) {
        userService.deleteUserById(id);
    }

}

以上代码中，我们使用了注解@ApiModel、@ApiModelProperty来快速自动生成API文档。其中，@ApiModel用于指定实体类作为model，并指定其属性，而@ApiModelProperty则是对实体类属性进行说明，从而生成API文档。通过这种方式，我们可以少写很多配置，快速生成API文档。

4. 总结

Knife4j是一款非常优秀的在线API文档管理框架，它不仅方便了API文档的管理和编写，同时也提升了我们的团队协作中的工作效率。希望以上攻略对于你了解Knife4j的使用有所帮助。