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的优势

功能强大: Knife4j提供了丰富的文档生成和管理功能。
操作简便: 通过简单的配置和注解,即可生成完整的API文档。
美观易用: Knife4j拥有现代化的UI设计,使用体验流畅。
高度可定制: 可以根据项目需求进行深度定制。
在线调试: 支持在线发送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实例@Beanpublic 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. 最佳实践

版本控制: 在ApiInfo中明确指定API版本,并考虑使用多个Docket Bean来管理不同版本的API。
细致的文档注释: 充分利用各种注解,为每个API端点提供详细的描述、参数说明和响应示例。
示例值: 为复杂的请求体或响应提供示例值,帮助API消费者更好地理解数据结构。
错误码说明: 在文档中明确列出可能的错误码及其含义。
定期更新: 将API文档的更新纳入开发流程,确保文档始终与实际API保持同步。
权限控制: 如果API有不同的访问级别,在文档中清晰标注每个接口的权限要求。

7. 导出离线文档

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

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

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

8. 结语

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