Knife4j 生成 API 文档

本文主要是介绍Knife4j 生成 API 文档，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

Knife4j 简介

Knife4j 是一个增强的 Swagger 文档生成工具，提供了更加友好的界面和更多功能，使得 API 文档更加美观且易于使用。它是基于 Spring Boot 和 Swagger 进行封装的，因此非常适合 Spring Boot 项目。

使用步骤

第一步：添加依赖

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

第二步：配置 Swagger 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()//TODO 改成自己的包名.apis(RequestHandlerSelectors.basePackage("com.example.hac.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API 文档").description("API 接口文档的描述信息").version("1.0").build();}
}

第三步：配置 application.yml

knife4j:enable: true  # 启用 Knife4j 功能 springdoc:api-docs:enabled: true  # 启用 SpringDoc API 文档生成 swagger-ui:enabled: true  # 启用 Swagger UI 界面 

Knife4j 常用注解的列表

注解	作用	示例
@Api	标注在类上，用于描述该类的作用和功能，可以分组管理 API。	@Api(tags = "用户管理")
@ApiOperation	标注在方法上，用于描述一个具体的操作（HTTP 请求），包括操作的功能、描述和其他细节。	@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
@ApiModel	标注在类上，用于描述一个 Model（实体类）的详细信息。	@ApiModel(value = "用户信息")
@ApiModelProperty	标注在实体类的属性上，用于描述属性的详细信息，如字段说明、示例值等。	@ApiModelProperty(value = "用户名字", example = "张三")
@ApiParam	标注在方法参数上，用于描述参数信息，如参数名称、类型、是否必填等。	@ApiParam(name = "id", value = "用户ID", required = true)
@ApiResponse	标注在方法上，用于描述单个 HTTP 响应。	@ApiResponse(code = 200, message = "请求成功")
@ApiResponses	标注在方法上，用于描述多个 HTTP 响应。	@ApiResponses({@ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 404, message = "未找到")})
@ApiImplicitParam	标注在方法上，用于描述单个隐式参数。	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "query")
@ApiImplicitParams	标注在方法上，用于描述多个隐式参数。	@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "query")})
@ApiIgnore	用于忽略某个类、方法或参数，使其不在 Swagger 文档中显示。	@ApiIgnore

案例

第一步：定义一个pojo

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(value = "用户信息")
public class User {@ApiModelProperty(value = "用户名字", example = "1")private String name;@ApiModelProperty(value = "用户年龄", example = "20")private String age;
}

第二步：编写controller service mapper

@RestController
@RequestMapping(value = "/users")
@Api(tags = "用户管理")
public class TestController {@Autowiredprivate TestService testService;@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")@GetMapping(value = "/{id}")public User getById(@PathVariable("id") int id) {return testService.getById(id);}
}

第三步：启动项目 访问：http://localhost:8080/doc.html

注意

可能会遇到这个错误Failed to start bean 'documentationPluginsBootstrapper';

原因：这个错误是因为 Spring Boot 2.6.0 中引入了新的路径模式匹配策略，而 Swagger 3.0.0 使用了旧的路径匹配策略。这导致了 documentationPluginsBootstrapper 的启动失败
解决方法1：
在application.yml中添加下面这

spring:mvc:pathmatch:matching-strategy: ANT_PATH_MATCHER

解决方法2：降低 Spring Boot 的版本

 <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.4.5</version></parent>

---

❤觉得有用的可以留个关注❤

这篇关于Knife4j 生成 API 文档的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！

---