Knife4j的介绍与使用

news2024/12/29 11:05:21

一、简单介绍

1.1 简介

Knife4j 是一款基于Swagger的开源文档管理工具，主要用于生成和管理 API 文档。
它提供了一套美观、功能强大的界面，可以帮助开发者快速浏览、测试和理解后端 API 接口。

1.2 主要特点和功能：

Swagger 兼容性：

Knife4j 基于 Swagger，能够兼容 Swagger 的各种功能和注解，支持生成符合 OpenAPI 规范的文档。

可视化界面：

Knife4j 提供了直观的可视化界面，展示 API 接口的详细信息，包括请求、响应、参数说明等。

在线调试和测试：

在 Knife4j 的界面中，可以直接对 API 进行调试和测试，支持修改参数、发送请求并查看响应结果，方便开发者进行接口的验证和调试。

权限控制：

可以配置权限控制，限制特定用户或角色访问和操作 API 文档，保障接口的安全性。

自定义配置：

Knife4j 提供了丰富的配置选项，开发者可以根据项目需求进行自定义配置，如修改 UI 样式、调整文档的展示内容等。

集成简便：

集成 Knife4j 到项目中相对简单，一般通过 Maven 或 Gradle 添加依赖，并在 Spring Boot 项目中配置即可快速启用。

二、使用步骤：

2.1 添加依赖：

在项目的 Maven 或 Gradle 配置文件中添加 Knife4j 的依赖。

Maven 示例：

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

2.2 yml数据源配置

spring:
  datasource:
    driver-class-name: com.mysql.jdbc.Driver
    url: jdbc:mysql://localhost:3306/database?serverTimezone=UTC
    username: root
    password: root
    # 数据库连接池
    type: com.alibaba.druid.pool.DruidDataSource
  mvc:
    pathmatch: # Springfox使用的路径匹配是基于AntPathMatcher的
      # 所以需要配置此参数
      matching-strategy: ant_path_matcher

2.3 创建knife4j配置类

@Configuration // 开启配置
@EnableSwagger2 // 启动Swagger2
public class Knife4jConfiguration {

    @Bean
    public Docket defaultApi2() {
        String groupName = "1.0版本";
        Docket docket = new Docket(DocumentationType.OAS_30)
                // 是否启用Swagger，true启用，false不启用
                .enable(true)
                .apiInfo(new ApiInfoBuilder()
                        .title("这是LiCoffee-Test-knife4j API ")
                        .description("这是项目描述")
                        .termsOfServiceUrl("服务器URL")
                        .contact(new Contact("LiCoffee", null, "qiushiju0828@163.com"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName(groupName)
                .select()
                // 这里指定Controller扫描包路径,没有加注解的接口方法也会生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.controller"))

                // 这里指定只有加了注解的才会生成接口文档
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

以上就配置完了，还有一些小细节下在讲，通过访问http://localhost:8080[/项目名]/doc.html

在这里插入图片描述

2.4 注解的作用

@Api(tags = "接口描述信息")

添加在controller层的类上

在这里插入图片描述

    @ApiOperation("根据用户ID查找")

添加在方法上

在这里插入图片描述

其他

@ApiModel：用对象来接收参数，修饰类

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

例如：

@ApiModel(description = "用户实体类")
public class User {
    @ApiModelProperty(name="id", value="用户id")
    private Integer id;
    @ApiModelProperty(value="用户姓名")
    private String name;

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述，一般描述错误的响应

// 针对响应状态 修饰方法
@ApiResponses({
            @ApiResponse(code=500, message = "服务器异常")
    })

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiParam：单个参数描述，用在控制器的方法上

@ApiImplicitParam：一个请求参数，用在方法上

@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")

@ApiImplicitParams({
            @ApiImplicitParam(),
            @ApiImplicitParam()
    })

针对返回值，使用泛型表示

@ApiModel
public class R {

    @ApiModelProperty(value = "返回数据状态",notes = "200成功 500失败")
    private int code;
    private String msg;
    @ApiModelProperty(value = "返回数据",notes = "可以是具体的对象，也可以是null")
    private Object data;