自学内容网 自学内容网
自学内容网 > 正文

Knife4j 初学习

🕗 发布于 2024-11-18 18:19 学习  


●官方文档：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j
●码云地址：knife4j: Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案
●示例地址：swagger-bootstrap-ui-demo: knife4j 以及swagger-bootstrap-ui 集成框架示例项目

Knife4j完全遵循Swagger的使用方法，可以无缝衔接

使用方法

引入依赖

首先，先要在pom.xml中导入依赖，具体版本可见Maven Repository: com.github.xiaoymin » knife4j-openapi2-spring-boot-starter

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>

不需要再引入 Swagger 所需的 springfox-boot-starter了，因为 Knife4j 的 starter 里面已经加入过了。

 创建配置类

第二布，创建一个 Java 配置类（例如 Knife4jConfig.java），并使用 @EnableKnife4j  注解启用 Knife4j。

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                .select()
                //apis： 添加swagger接口提取范围
                .apis(RequestHandlerSelectors.basePackage("www.paicoding.controller"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("技术派")
                .description("一个基于 Spring Boot、MyBatis-Plus、MySQL、Redis、ElasticSearch、MongoDB、Docker、RabbitMQ 等技术栈实现的社区系统，采用主流的互联网技术架构、全新的UI设计、支持一键源码部署，拥有完整的文章&教程发布/搜索/评论/统计流程等，代码完全开源，没有任何二次封装，是一个非常适合二次开发/实战的现代化社区项目👍 。")
                .contact(new Contact("沉默王二", "https://paicoding.com","www.qing_gee@163.com"))
                .version("v1.0")
                .build();
    }
}

或者不创建配置类，通过application.yml 文件中设置属性来达到相同的目的。

knife4j:
  enable: true
  openapi:
    title: 技术派
    description: 一个基于 Spring Boot、MyBatis-Plus、MySQL、Redis、ElasticSearch、MongoDB、Docker、RabbitMQ 等技术栈实现的社区系统，采用主流的互联网技术架构、全新的UI设计、支持一键源码部署，拥有完整的文章&教程发布/搜索/评论/统计流程等，代码完全开源，没有任何二次封装，是一个非常适合二次开发/实战的现代化社区项目👍 。
    version: 1.0.0
    concat:
      - 一灰灰 | 楼仔 | 沉默王二
      - https://paicoding.com
      - https://github.com/itwanger/paicoding
    license: Apache License 2.0
    license-url: https://github.com/itwanger/paicoding/blob/main/License
    email: bangzewu@126.com
    group:
      admin:
        group-name: 后台接口分组
        api-rule: package
        api-rule-resources:
          - com.github.paicoding.forum.web.admin
      front:
        group-name: 前台接口分组
        api-rule: package
        api-rule-resources:
          - com.github.paicoding.forum.web.front

在以前的版本中，我们需要在配置文件中手动使用 @EnableKnife4j 来使用增强，自 2.0.6 版本后，只需要在配置文件中配置 knife4j.enable=true 即可。

配置属性

  1. knife4j.enable:设置true启动Knife4j，将在应用程序中启动Knife4j UI
  2. knife4j.openapi: 这个属性包含了 Swagger API 文档的基本元数据信息，例如标题、描述、版本等。
    1. title: API 文档的标题。
    2. description: API 文档的详细描述。
    3. version: API 文档的版本号。
    4. concat: API 文档的作者信息。包括作者名、网站和 GitHub 仓库。
    5. license: API 文档的许可证类型。
    6. license-url: API 文档许可证的链接。
    7. email: API 文档作者的联系邮箱。
  3. knife4j.group: 定义 API 分组。这里有两个分组：admin 和 front。
    1. admin:后台接口分组
      1. group-name: 分组名称。
      2. api-rule: 分组规则，这里使用的是包规则。
      3. api-rule-resources: 指定包名，Knife4j 将扫描此包下的所有 API 接口并将它们添加到此分组。
    2. front: 前台接口分组，它下面的属性不再赘述，和 admin 一样。

在测试类中添加接口

第三步，在测试类中添加 knife4j 的接口。

@ApiOperation("测试 Knife4j")
@RequestMapping(value ="/testKnife4j", method = RequestMethod.POST)
public String testKnife4j() {
    return "沉默王二又帅又丑";
}

 三个注释含义

@ApiOperation、@ApiParam、@ApiModel

  1. @ApiOperation：用于描述一个具体的 API 操作。通常用于标注在 Controller 类的方法上。它有以下三个主要属性：
    1. value：API 操作的简短描述，会显示在 API 文档中。
    2. notes：API 操作的详细描述，会显示在 API 文档中。
    3. tags：API 操作的标签，用于对 API 进行分类和分组

      例如： 
      
@ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户详细信息")
  2. @ApiParam：用于描述 API 操作的参数。通常用于标注在 Controller 类的方法参数上。它有以下主要属性：
    1. name：参数名称。
    2. value：参数描述。
    3. required：指示参数是否是必需的，默认为 false。
    4. defaultValue：参数的默认值。
    5. allowableValues：允许的参数值范围。

      例如： 
      
public ResponseEntity<User> getUser(@ApiParam(value = "用户 ID", required = true) @PathVariable("id") Long id) {
    // ...
}
  3. @ApiModel：用于描述一个 API 操作返回的数据模型或请求数据模型。通常用于标注在实体类或 DTO 类上。它有以下主要属性：
    1. value:模型名称
    2. description：模型描述。
      例如： 
      @ApiModel(value = "用户", description = "用户详细信息")
public class User {
    // ...
}

运行项目

第四步，运行项目，然后在浏览器地址栏输入 http://localhost:8080/doc.html 就可以看到 API 文档了。

Knife4j 的优点

Knife4j 在 Swagger 的基础上增加了一些实用功能，优化了 UI 界面，使得 API 文档更具可读性和易用性。简单来介绍下 Knife4j 的 功能特点：

生产环境屏蔽

如果我们需要在生产环境下屏蔽 Swagger 的相关资源，只需要在 application.yml 中添加这样一个配置即可。

# 开启生产环境屏蔽
production: true

采坑提示，配置中至少需要有一个 knife4j.setting 选项。比如说：


knife4j:
  setting:
    language: zh-CN

否则直接报错。

访问页面加权控制

默认情况下，所有的用户都可以无限制访问 doc.html，也就是 Knife4j 主页，如果需要增加权限，可以在 application.yml 文件中添加 Basic认证功能。

basic:
  enable: true
  # 配置Basic认证的用户名和密码
  username: admin
  password: 123456

然后访问就需要用户名和密码登录

支持 afterScript 

针对 JWT 类型的接口，调用登录接口后，每个接口请求时需要带上Token参数，此时可以通过脚本动态赋值全局 token 参数，省去复制粘贴的麻烦。


var code=ke.response.data.code;
if(code==8200){
    //判断,如果服务端响应code是8200才执行操作
    //获取token
    var token=ke.response.data.data.token;
    //1、如果参数是Header，则设置当前逻辑分组下的全局Header
    ke.global.setHeader("token",token);

}

 支持全局参数

当某些请求需要全局参数时，这个功能就很实用了，可以在左侧菜单「文档管理」中找到该功能。Knife4j 支持 header 和 query 两种方式。

支持离线文档

Knife4j 支持把 API 文档导出为离线文档（支持 markdown 格式、HTML 格式、Word 格式等）。

支持JSON 折叠

Swagger 是不支持 JSON 折叠的，当返回的信息非常多的时候，界面就会显得非常的臃肿。Knife4j 则不同，可以对返回的 JSON 节点进行折叠。

支持搜索 API 接口

Swagger 是没有搜索功能的，当要测试的接口有很多的时候，当需要去找某一个 API 的时候就傻眼了，只能一个个去拖动滚动条去找。在文档的右上角，Knife4j 提供了文档搜索功能，输入要查询的关键字，就可以检索筛选了，是不是很方便？

目前支持搜索接口的地址、名称和描述。


原文地址：https://blog.csdn.net/2301_80482258/article/details/143830126

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！

相关文章

自学内容网
Copyright © 2015-2024