开发者

SpringBoot中使用Knife4j生成接口文档的示例详解

目录
  • 前言
  • 一、Knife4j 简介
  • 二、Spring Boot 集成 Knife4j
    • 1. 添加依赖
    • 2. 启用 Knife4j
  • 三、常用注解说明
    • 1. 控制器级别注解
    • 2. 方法级别注解
    • 3. 参数对象字段注解
  • 四、访问 Knife4j 文档页面
    • 五、常见问题与注意事项
      • 1. Spring Boot 3.x 下无法访问/doc.html
      • 2. 参数没有显示注释
      • 3. 多个接口分组展示
    • 六、总结

      前言

      Knife4j 是一个基于 Swagger 的增强 UI 实现,主要用于为 Spring Boot 应用程序生成 API 接口文档。它不仅支持标准的 OpenAPI 规范,还提供了更加友好的界面和强大的功能。本文将详细介绍如何在 Spring Boot 中集成 Knife4j,并通过不同注解来生成清晰的接口文档。同时,我们也会比较 Spring Boot 2.x 和 Spring Boot 3.x 版本中使用 Knife4j 的差异。

      一、Knife4j 简介

      Knife4j 是 Swagger 的增强工具包,其核心特性包括:

      • 支持 OpenAPI 2.0 / 3.0
      • 提供更美观的 UI 界面
      • 支持接口调试
      • 支持分组管理
      • 支持离线文档导出(HTML/PDF)

      二、Spring Boot 集成 Knife4j

      1. 添加依赖

      Spring Boot 2.x(基于 Swagger 2)

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

      Spring Boot 3.x(基于 Swagger 3/OpenAPI 3.0)

      从 Spring Boot 3.x 开始,官方全面转向 Jakarta EE 9+,包名由 Javax 变更为 jakarta,因此需要使用适配 Jakarta 的版本。

      <dependency>
          <groupId>com.github.xiaoymin</groupId>
          <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
          <version>4.5.0</version>
      </dependency>
      

      注意:Spring Boot 3.x 使用的是 OpenAPI 3.0,而不再是 Swagger 2。

      2. 启用 Knife4j

      创建配置类或直接在主启动类上添加注解启用 Knife4j。

      Spring Boot 2.x

      import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
      import org.springframework.context.annotation.Configuration;
      import springfox.documentation.swagger2.annotations.EnableSwagger2;
      
      @Configuration
      @EnableSwagger2
      @EnableKnijavascriptfe4j
      publicpython class SwaggerConfig {
      }
      

      Spring Boot 3.x

      import com.github.xiaoymin.knife4j.core.constants.Knife4jOpenApi3UrlConstant;
      import com.github.xiaoymin.knife4j.openap3.configuration.OpenApi3Configuration;
      import com.github.xiaoymin.knife4j.spring.boot.extension.OpenApi3ExtensionResolver;
      import io.swagger.v3.oas.models.OpenAPI;
      import io.swagger.v3.oas.models.info.Info;
      import org.springframework.context.annotation.Bean;
      import org.springframework.context.annotation.Configuration;
      
      @Configuration
      public class SwaggerConfig {
      
          @Bean
          public OpenAPI customOpenAPI() {
              return new OpenAPI()
                      .info(new Info()
                              .title("Spring Boot 3.x Knife4j 示例")
                              .version("1.0")
                              .description("基于 OpenAPI 3.0 的接口文档"));
          }
      
          // 必须加上这个 Bean 才能启用 Knife4j 的扩展功能
          @Bean
          public OpenApi3ExtensionResolver openApi3ExtensionResolver() {
              return new OpenApi3ExtensionResolver();
          }
      }
      

      三、常用注解说明

      1. 控制器级别注解

      注解描述Spring Boot 版本
      @Api(tags = "用户管理")用于类上,表示该控制器对应的功能模块名称2.x & 3.x
      @RequestMapping("/user")定义请求路径通用

      示例:

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

      2. 方法级别注解

      注解描述Spring Boot 版本
      @ApiOperation(value = "获取用户列表", notes = "返回所有用户信息")描述方法用途2.x
      @Operation(summary = "获取用户列表", description = "返回所有用户信息")OpenAPI 3.0 替代方案3.x
      @ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int")})描述参数(适用于非实体对象参数)2.x
      @Parameters({@Parameter(name = "pageNum", description = "页码", required = true)})OpenAPI 3.0 替代方案3.x

      示例:

      Spring Boot 2.x

      @GetMapping("/list")
      @ApiOperation(value = "获取用户列表", notes = "返回所有用户信息")
      @ApiImplicitParams({
          @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int"),
          @ApiImplicitParam(name = "pageSize", value = "每页数量", required = false, dataType = "int")
      })
      public List<User> listUsers(int pageNum, int pageSize) {
          return userService.list(pageNum, pageSize);
      }
      

      Spring Boot 3.x

      @GetMapping("/list")
      @Operation(summary = "获取用户列表", description = "返回所有用户信息")
      @Parameters({
          @Parameter(name = "pageNum", description = "页码", required = true),
          @Parameter(name = "pageSize", description = "每页数量", required = false)
      })
      public List<User> listUsers(int pageNum, int pageSize) {
          return userService.list(pageNum, pageSize);
      }
      

      3. 参数对象字段注解

      当使用实体类接收参数时,可以对字段进行描述。

      注解描述Spring Boot 版本js
      @ApiModelProperty(value = "用户名", example = "admin")描述字段含义及示例值2.x
      @Schema(description = "用户名", example = "admin")OpenAPI 3.0 替代方案3.x

      示例:

      public class UserDTO {
          @Schema(description = "用户名编程客栈", example = "admin")
          private String username;
      
          @Schema(description = "密码", example = "123456")
          private String password;
      }
      

      四、访问 Knife4j 文档页面

      启动项目后,访问以下地址查看接口文档:

      Spring Boot 2.x:http://localhost:8080/knife4j-ui.html

      Spring Boot 3.x:http://localhost:8080/doc.html

      五、常见问题与注意事项

      1. Spring Boot 3.x 下无法访问/doc.html

      请确保你使用了正确的 Starter 包(带 openapi3-jakarta 字样),并且正确配置了 OpenAPI Bean。

      2. 参数没有显示注释

      确保你在实体类字段上使用了 @Schema@ApiModelProperty 注解,并且开启了相应的自动扫描。

      3. 多个接口分组展示

      可以通过 Docket(Spring Boot 2.x)或 OpenAPI + 分组配置(Spring Boot 3.x)实现多组接口文档。

      六、总结

      功能Spring Boot 2.xSpring Boot 3.x
      依赖包knife4j-spring-boot-starterknife4j-openapi3-jakarta-spring-boot-starter
      核心注解@Api、@ApiOperation、@ApiImplicitParam、@ApiModelProperty@Tag、@Operation、@Parameter、@Schema
      访问地址/knife4j-ui.html/doc.html
      默认协议Swagger 2.编程0OpenAPI 3.0

      以上就是SpringBoot中使用Knife4j生成接口文档的示例详解的详细内容,更多关于SpringBoot Knife4j生成接口文档的资料请关注编程客栈(www.devze.com)其它相关文章!

      0

      上一篇:

      下一篇:

      精彩评论

      暂无评论...
      验证码 换一张
      取 消

      最新开发

      开发排行榜