knife4j接口文档生成工具

knife4j的官方文档写了好多个版本的使用方法，感觉很混乱，尤其是像我没怎么使用过swagger的人来说，完全不知道使用哪个版本。下面是spring-boot2.7使用knife4j使用笔记，我是跟着黑马老师写的，一切功能都正常。

spring-boot2

导入maven依赖

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

配置

然后写一个配置文件，进行swagger（或者说knife4j）的配置:

package com.akbar.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    /*
    * knife4j生成接口文档
    * */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("1.0")
                .description("苍穹外卖项目接口文档")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.akbar.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /*
    * 设置静态资源映射
    * */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 访问doc.html就就可以看到api文档
        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

配置信息解释（chatgpt回答）：

• Docket：Knife4j/Swagger 的核心配置类，用来设置 API 文档的生成规则。
• apiInfo：定义 API 文档的一些基本信息，例如标题、版本和描述。
• select()：用于选择 API 的控制器类，这里使用 RequestHandlerSelectors.basePackage("com.akbar.controller") 来指定扫描 com.akbar.controller 包下的所有控制器类。
• paths(PathSelectors.any())：表示扫描所有路径下的接口。
• DocumentationType.SWAGGER_2：指定使用 Swagger 2 类型来生成文档。

常用注解

在控制器中使用

package com.akbar.controller.admin;

import com.akbar.dto.EmployeeLoginDTO;
import com.akbar.entity.Employee;
import com.akbar.result.Result;
import com.akbar.service.EmployeeService;
import com.akbar.vo.EmployeeLoginVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/admin/employee")
@Slf4j
@Api(tags = "用户管理接口") //接口分组
public class EmployeeController {

    @Autowired
    private EmployeeService employeeService;

    /*
    * 员工登录
    * */
    @PostMapping("/login")
    @ApiOperation(value = "用户登录")  //接口描述，value可以省略
    public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) {
        log.info("员工登录：{}", employeeLoginDTO);

        Employee employee =  employeeService.login(employeeLoginDTO);

        EmployeeLoginVO employeeLoginVO = EmployeeLoginVO.builder()
                .id(employee.getId())
                .userName(employee.getUsername())
                .name(employee.getName())
                .token(null)
                .build();

        return Result.success(employeeLoginVO);
    }
}

在类和类属性上面使用注解：

package com.akbar.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;
}

5.访问api文档

spring-boot3

maven依赖：

<!--knife4j 接口文档-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

在config包下创建一个SwaggerConfig类，用knife4j的配置：

package com.akbar.config;

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 openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("实训后端")
                        .version("1.0")
                        .description( "暑期实训项目后端"));
    }
}

也可以写更多信息，比如：

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("XXX用户系统API")
                        .version("1.0")
                        .description( "Knife4j集成springdoc-openapi示例")
                        .termsOfService("http://doc.xiaominfo.com")
                        .license(new License().name("Apache 2.0")
                                .url("http://doc.xiaominfo.com")));
    }

在springboot的yml文件中进行配置：

# springdoc和swagger配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
  api-docs:
    path: /v3/api-docs

knife4j:
  enable: true
  setting:
    language: zh_cn
    enable-document-manage: false
    swagger-model-name: 实体类列表
    enable-version: false
    enable-after-script: false
  basic:
    enable: false

更多的配置信息请看：doc.xiaominfo.com/docs/featur…

因为springboot3版本是OpenAPI 3 规范，底层使用 springdoc-openapi 替代 Springfox

对应的注解：

Swagger2 (Springfox)	OpenAPI3 (springdoc-openapi / Knife4j Spring Boot 3)
@Api	@Tag
@ApiOperation	@Operation
@ApiParam	@Parameter
@ApiModel	@Schema（在类上）
@ApiModelProperty	@Schema（在字段上）
@ApiIgnore	@Hidden

示例代码：

package com.akbar.controller;

import com.akbar.pojo.User;
import com.akbar.service.UserService;
import com.akbar.util.Result;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("user")
@Tag(name="用户模块")
public class UserController {

    @Autowired
    private UserService userService;


    // 用户注册接口
    @PostMapping
    @Operation(summary = "示例接口")
    public Result<String> register(@RequestBody User user) {
        userService.register(user);
        return Result.success();
    }
}