Knife4j:打造优雅的SpringBoot API文档

1. 为什么需要API文档？

在现代软件开发中,API文档的重要性不言而喻。一份清晰、准确、易于理解的API文档不仅能够提高开发效率,还能降低前后端沟通成本。今天,我们要介绍的Knife4j正是这样一款强大的API文档生成工具,它专为Spring Boot项目量身打造,让API文档的生成和管理变得轻而易举。当然了，还有别的很好用的API文档生成工具：PostMan、ApiPost等。

2. Knife4j简介

Knife4j是一个基于Swagger 2.0标准构建的文档生成工具。它不仅继承了Swagger的强大功能,还在用户体验和功能扩展上做了大量优化。

2.1 Knife4j的优势

1. 功能强大: Knife4j提供了丰富的文档生成和管理功能。
2. 操作简便: 通过简单的配置和注解,即可生成完整的API文档。
3. 美观易用: Knife4j拥有现代化的UI设计,使用体验流畅。
4. 高度可定制: 可以根据项目需求进行深度定制。
5. 在线调试: 支持在线发送API请求,方便开发和测试。

3. Knife4j快速入门

3.1 添加依赖

首先,在你的Spring Boot项目的pom.xml文件中添加Knife4j依赖:

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

3.2 配置Swagger

创建一个配置类,例如Knife4jConfig:

package cn.postgraduate.postgraduateapi.base.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
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 Knife4jConfig {
    //配置Swagger2的Docket的Bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // apiInfo()：配置 API 的一些基本信息，比如：文档标题title，文档描述description，文档版本号version
                .apiInfo(apiInfo())
                // select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
                .select()
                // apis()：指定要生成哪个包下的 API 文档
//                .apis(RequestHandlerSelectors.basePackage("cn.postgraduate.postgraduateapi.*.controller"))
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
    }

    //文档信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("postgraduate项目")
                // 文档描述信息
                .description("postgraduate项目在线API文档")
                // 文档版本号
                .version("1.0")
                .contact(new Contact("postgraduate", "", "邮箱"))
                .build();
    }
}

3.3 访问文档

启动你的Spring Boot应用后,访问http://localhost:8080/doc.html即可查看生成的API文档。
如果yaml文件里面定义了别的端口，8080需要替换为别的端口。效果在这里哦🎉

4. Knife4j常用注解详解

Knife4j沿用了Swagger的注解体系,通过这些注解,我们可以非常精确地控制API文档的内容和展示方式。

4.1 @Api

用于类上,标记该类是一个Swagger资源。

@Api(tags = "用户管理")
@RestController
public class UserController {
    // ...
}

4.2 @ApiOperation

用于方法上,描述一个API操作。

@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@PostMapping("/user")
public ResponseEntity<User> createUser(@RequestBody User user) {
    // ...
}

4.3 @ApiModelProperty

用于模型类的属性上,描述模型属性。

public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;

    @ApiModelProperty(value = "用户名", required = true, example = "john_doe")
    private String username;
    
    // ...
}

4.4 @ApiImplicitParam 和 @ApiImplicitParams

用于方法上,描述API的参数。

@ApiOperation("获取用户信息")
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
    @ApiImplicitParam(name = "fields", value = "指定返回字段", dataType = "String")
})
@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id, @RequestParam(required = false) String fields) {
    // ...
}

4.5 @ApiIgnore

用于方法或参数上,指示Swagger忽略这个方法或参数。

@ApiOperation("更新用户")
@PutMapping("/user/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user, @ApiIgnore HttpSession session) {
    // ...
}

5. Knife4j高级特性(拓展)

5.1 接口分组

Knife4j支持对API接口进行分组,这对于大型项目特别有用。

@Bean
public Docket userApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户API")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.user"))
            .build();
}

@Bean
public Docket orderApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("订单API")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.order"))
            .build();
}

5.2 自定义响应消息

你可以自定义API的响应消息,使文档更加清晰。

@Bean
public Docket customImplementation() {
    return new Docket(DocumentationType.SWAGGER_2)
            .useDefaultResponseMessages(false)
            .globalResponseMessage(RequestMethod.GET,
                    newArrayList(new ResponseMessageBuilder()
                            .code(500)
                            .message("服务器发生异常")
                            .responseModel(new ModelRef("Error"))
                            .build(),
                            new ResponseMessageBuilder()
                                    .code(403)
                                    .message("禁止访问")
                                    .build()));
}

5.3 整合Spring Security

如果你的项目使用了Spring Security,可以配置Knife4j支持认证:

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .securityContexts(Lists.newArrayList(securityContext()))
            .securitySchemes(Lists.newArrayList(apiKey()))
            // ...
}

private ApiKey apiKey() {
    return new ApiKey("JWT", "Authorization", "header");
}

private SecurityContext securityContext() {
    return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .build();
}

List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Lists.newArrayList(new SecurityReference("JWT", authorizationScopes));
}

6. 最佳实践

1. 版本控制: 在ApiInfo中明确指定API版本,并考虑使用多个Docket Bean来管理不同版本的API。

2. 细致的文档注释: 充分利用各种注解,为每个API端点提供详细的描述、参数说明和响应示例。

3. 示例值: 为复杂的请求体或响应提供示例值,帮助API消费者更好地理解数据结构。

4. 错误码说明: 在文档中明确列出可能的错误码及其含义。

5. 定期更新: 将API文档的更新纳入开发流程,确保文档始终与实际API保持同步。

6. 权限控制: 如果API有不同的访问级别,在文档中清晰标注每个接口的权限要求。

7. 导出离线文档

Knife4j支持导出多种格式的离线文档,包括OpenAPI、Markdown和HTML等。这个功能在以下场景特别有用:

1. 团队协作: 可以将API文档共享给不同角色的团队成员。
2. 版本管理: 对于每次重大更新,可以导出一份文档作为存档。
3. 客户交付: 如果你在为客户开发API,离线文档是一个很好的交付物。

要导出文档,只需在Knife4j的Web界面中点击"文档管理" -> “离线文档”,然后选择你想要的格式即可。

8. 结语

Knife4j为Spring Boot项目提供了一种优雅而强大的API文档解决方案。通过简单的配置和注解,开发者可以快速生成美观、互动的API文档,大大提高了开发效率和API的可用性。在实际项目中,合理使用Knife4j不仅可以改善团队协作,还能为API消费者提供更好的体验。希望这篇文章能够帮助你更好地使用Knife4j,创建出优秀的API文档。