Knife4j 生成 API 文档

文章目录

    • [Knife4j 简介](#Knife4j 简介)
    • 使用步骤
    • [Knife4j 常用注解的列表](#Knife4j 常用注解的列表)
    • 案例
    • 注意

Knife4j 简介

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

使用步骤

第一步:添加依赖

xml 复制代码
 <dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>3.0.3</version>
 </dependency>

第二步:配置 Swagger 配置类

java 复制代码
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 {

    @Bean
    public 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

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

java 复制代码
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

java 复制代码
@RestController
@RequestMapping(value = "/users")
@Api(tags = "用户管理")
public class TestController {
    @Autowired
    private 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中添加下面这

yml 复制代码
spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

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

xml 复制代码
 <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>2.4.5</version>
 </parent>

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

相关推荐
缺点内向3 小时前
Java:创建、读取或更新 Excel 文档
java·excel
带刺的坐椅4 小时前
Solon v3.4.7, v3.5.6, v3.6.1 发布(国产优秀应用开发框架)
java·spring·solon
四谎真好看5 小时前
Java 黑马程序员学习笔记(进阶篇18)
java·笔记·学习·学习笔记
桦说编程5 小时前
深入解析CompletableFuture源码实现(2)———双源输入
java·后端·源码
java_t_t5 小时前
ZIP工具类
java·zip
lang201509286 小时前
Spring Boot优雅关闭全解析
java·spring boot·后端
pengzhuofan7 小时前
第10章 Maven
java·maven
百锦再7 小时前
Vue Scoped样式混淆问题详解与解决方案
java·前端·javascript·数据库·vue.js·学习·.net
刘一说7 小时前
Spring Boot 启动慢?启动过程深度解析与优化策略
java·spring boot·后端
壹佰大多7 小时前
【spring如何扫描一个路径下被注解修饰的类】
java·后端·spring