Spring Boot集成Knife4j文档工具

server/2024/12/15 21:21:17/

Knife4j 搭建

Knife4j环境的的搭建和Swagger一样都比较简单,只需要极简的配置即可。

maven依赖

我使用的是较高版本的基于openapi规范的依赖包,OpenAPI2(Swagger)规范是Knife4j之前一直提供支持的版本,底层依赖框架为Springfox

此次在4.0版本开始Knife4j有了新的变化,主要有以下几点:

  • Springfox版本选择的依然是2.10.5版本,而并非springfox最新3.0.0版本

  • 不支持以Springfox框架为基础的OpenAPI3规范,放弃Springfox项目的后续版本适配支持工作

  • Spring Boot 版本建议 2.4.0~3.0.0之间

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><version>2.7.6</version>
</dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.3.0</version>
</dependency>

创建接口

我们创建两个控制器controller类,并创建几个API方法加上@Api@ApiOperation@ApiParam注解,更多的注解使用可以参考Sprinboot 集成 Swagger3.0 详解。

BuyController

import com.springboot101.po.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;@RequestMapping("/buy")
@Api(tags = "商家管理")
@RestController
public class BuyController {@ApiOperation("创建商家")@PostMapping("/createBuy")public ResponseEntity<User> createUser(@RequestBody User user) {return ResponseEntity.ok(user);}@ApiOperation("更新商家")@PostMapping("/updateBuy/{id}")public ResponseEntity<User> updateUser(@ApiParam(value = "商家主键ID", required = true) @PathVariable("id") String id,@RequestHeader("token") String token,@RequestParam("name") String name,@RequestBody User user) {return ResponseEntity.ok(user);}
}

UserController

import com.springboot101.po.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;@RequestMapping("/user")
@Api(tags = "用户管理")
@RestController
public class UserController {@ApiOperation("创建用户")@PostMapping("/createUser")public ResponseEntity<User> createUser(@RequestBody User user) {return ResponseEntity.ok(user);}@ApiOperation("更新用户")@PostMapping("/updateUser/{id}")public ResponseEntity<User> updateUser(@ApiParam(value = "用户主键ID", required = true) @PathVariable("id") String id,@RequestHeader("token") String token,@RequestParam("name") String name,@RequestBody User user) {return ResponseEntity.ok(user);}
}

Knife4j配置

在以前的版本中,开发者需要在配置类中手动使用@EnableKnife4j注解来使用增强功能,自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可,不在使用注解开启了。

@Configuration
@EnableKnife4j 
public class Knife4jConfig {}

而且自2.0.6版本开始,将UI界面中一些个性化配置从代码中剥离,我们可以直接在application.yml文件中配置文档属性,使用起来更加的简洁了。

# Knife4j配置
knife4j:# 开启增强配置enable: true#开启Basic登录认证功能openapi:title: xx官方文档description: ""email: 515361725@qq.comconcat: xxurl: http://xiaofucode.comversion: v1.0 # 版本号license: Apache 2.0license-url: https://fire100.topterms-of-service-url: https://fire100.top #API服务条款

默认情况下,如果不设置API的分组,Knife4j会扫描全部标注了@Api@ApiOperation等注解类,将它们全部放入到default分组。

图片

API分组

knife4j的分组支持我们在yml文件中配置,开启knife4j.openapi.group

例如:新建userbuy模块就代表了不同的分组,其中的子项:

  • group-name:分组的名称;

  • api-rule:组内资源扫描策略,目前支持根据package类路径扫描,annotation扫描特定注解;

  • api-rule-resources:资源路径(数组),策略为 package 时填写完整的controller类路径,策略为 annotation 时填写特定注解的完整路径;

# Knife4j配置
knife4j:# 开启增强配置enable: true#开启Basic登录认证功能openapi:title: xxdescription: "xx"email: 515361725@qq.comconcat: xxurl: http://xiaofucode.comversion: v1.0 # 版本号license: Apache 2.0license-url: https://fire100.topterms-of-service-url: https://fire100.top #API服务条款# API分组配置group:user:group-name: 用户管理 # 组名api-rule: package # 扫描规则,是根据包路径还是请求路径api-rule-resources: # 扫描的资源- com.springboot101.controller.userbuy:group-name: 商家管理api-rule: packageapi-rule-resources:- com.springboot101.controller.buy#user:
#        group-name: 用户管理
#        api-rule: annotation
#        api-rule-resources:
#          - io.swagger.annotations.Api   # 扫描带有 @Api 注解的接口
#      buy:
#        group-name: 商家管理
#        api-rule: annotation
#        api-rule-resources:
#          - io.swagger.annotations.Api   # 扫描带有 @Api 注解的接口

用户认证

knife4j内置了Basic认证,只要在开启basic下配置认证用户名和密码即可。

knife4j:#开启Basic登录认证功能basic:enable: true# Basic认证用户名username: admin# Basic认证密码password: 123456

再次访问文档路径时会弹出登录框。

图片

完整的knife4j配置

以下是knife4j的完整配置:

server:port: 9002# Knife4j配置
knife4j:# 开启增强配置enable: true#开启Basic登录认证功能basic:enable: true# Basic认证用户名username: admin# Basic认证密码password: 123456openapi:title: xxxdescription: "xx"email: 515361725@qq.comconcat: xxurl: http://xiaofucode.comversion: v1.0 # 版本号license: Apache 2.0license-url: https://fire100.topterms-of-service-url: https://fire100.top #API服务条款# API分组配置group:user:group-name: 用户管理 # 组名api-rule: package # 扫描规则,是根据包路径还是请求路径api-rule-resources: # 扫描的资源- com.springboot101.controller.userbuy:group-name: 商家管理api-rule: packageapi-rule-resources:- com.springboot101.controller.buy#user:
#        group-name: 用户管理
#        api-rule: annotation
#        api-rule-resources:
#          - io.swagger.annotations.Api   # 扫描带有 @Api 注解的接口
#      buy:
#        group-name: 商家管理
#        api-rule: annotation
#        api-rule-resources:
#          - io.swagger.annotations.Api   # 扫描带有 @Api 注解的接口

http://www.ppmy.cn/server/150444.html

相关文章

DETR: End-to-End Object Detection with Transformers论文学习

论文地址&#xff1a;https://arxiv.org/pdf/2005.12872 代码地址&#xff1a;https://github.com/facebookresearch/detr 相关学习视频&#xff1a;https://space.bilibili.com/94779326/lists?sid1531941 标题前言&#xff1a; DETR 是 Facebook 团队于 2020 年提出的基于…

控制反转IoC

什么是控制反转&#xff1f; 控制反转&#xff1a;IoC&#xff08;Inversion of Control&#xff09;&#xff0c;是一种编程思想。或者叫做一种新型的设计模式。由于出现的比较新&#xff0c;没有被纳入GoF23种设计模式范围内。 反转是什么呢&#xff1f; 反转的是两件事&a…

呼叫中心大模型呼入机器人详解(转)

呼叫中心大模型呼入机器人详解(转) 原作者&#xff1a;开源呼叫中心FreeIPCC&#xff0c;其Github&#xff1a;https://github.com/lihaiya/freeipcc 呼叫中心大模型呼入机器人是一种基于大规模深度学习模型构建的智能化系统&#xff0c;它能够处理海量数据并学习其中的规律&…

开源分布式系统追踪-01-Zipkin-01-入门介绍

分布式跟踪系列 CAT cat monitor 分布式监控 CAT-是什么&#xff1f; cat monitor-02-分布式监控 CAT埋点 cat monitor-03-深度剖析开源分布式监控CAT cat monitor-04-cat 服务端部署实战 cat monitor-05-cat 客户端集成实战 cat monitor-06-cat 消息存储 skywalking …

YZ系列工具之YZ11:VBA_窗体缩放

我给VBA下的定义&#xff1a;VBA是个人小型自动化处理的有效工具。利用好了&#xff0c;可以大大提高自己的工作效率&#xff0c;而且可以提高数据的准确度。我的教程一共九套一部VBA手册&#xff0c;教程分为初级、中级、高级三大部分。是对VBA的系统讲解&#xff0c;从简单的…

Vue八股青春版

前言&#xff1a;本文资料来自于web前端面试以及Vue的官方文档&#xff0c;对其中的信息做了更新和归纳。 对vue的理解 一、从历史说起 纯前端&#xff08;静态&#xff09;ASP和JSP &#xff08;JavaHTML&#xff09;&#xff0c;不太灵活&#xff0c;服务端渲染JquerySPA …

【自动化】requirements.txt

1.是什么&#xff1f; 用于列出项目依赖的所有Python包及其版本。这使得其他开发者可以轻松地安装与你的项目兼容的环境&#xff0c;或者在不同的机器上复制相同的开发环境。 2.如何编写requirements.txt 手动创建 格式&#xff1a; 包名版本号 在终端home命令自动生成 创建r…

mysqlelasticsearch备份恢复

目录 1. mysql备份 1.1. 使用 mysqldump 命令备份整个数据库&#xff1a; 1.2. 备份特定表&#xff1a; 2. 恢复 MySQL 数据库 2.1. 使用备份文件恢复数据库&#xff1a; 3. 备份elasticsearch索引 3.1. 注册本次备份的存储路径 3.2. 查看当前备份快照信息 3.3. 备份索…