经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置:技术经验 » Java相关 » Spring » 查看文章
Swagger系列:SpringBoot3.x中使用Knife4j
来源:cnblogs  作者:Code技术分享  时间:2023/10/19 10:04:15  对本文有异议

一、简介

官网:https://doc.xiaominfo.com/

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案

Knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案,前身是 swagger-bootstrap-ui,致力于 springfox-swagger 的增强 UI 实现。knife4j 为了契合微服务的架构发展,由于原来 swagger-bootstrap-ui 采用的是后端 Java 代码 + 前端 UI 混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为 knife4j,更名后主要专注的方面如下:

  • 后端 Java 代码以及前端 UI 模块进行了分离,在微服务架构下使用更加灵活
  • 提供专注于 Swagger 的增强解决方案,不同于只是单纯增强前端 UI 部分

二、版本说明

版本 说明
1.0~1.9.6 名称是叫swagger-bootstrap-ui,蓝色风格Ui
1.9.6 蓝色皮肤风格,开始更名,增加更多后端模块
2.0~2.0.5 Ui基于Vue2.0+AntdV重写,黑色风格,参考示例,底层依赖的springfox框架版本是2.9.2,仅提供Swagger2规范的适配
2.0.6~2.0.9 底层springfox框架版本升级知2.10.5,,仅提供Swagger2规范的适配
3.0~3.0.3 底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3,过度版本,建议开发者不要使用
4.0~ 区分OpenAPI2和Swagger3的Maven坐标artifactId OpenAPI2规范服务端解析框架稳定在springfox2.10.5 OpenAPI3框架服务端解析跟随springdoc项目更新迭代 建议开发者使用该版本,请参考4.x升级文档

Spring Boot版本兼容性

Spring Boot版本 Knife4j Swagger2规范 Knife4j OpenAPI3规范
1.5.x~2.0.0 <Knife4j 2.0.0 >=Knife4j 4.0.0
2.0~2.2 Knife4j 2.0.0 ~ 2.0.6 >=Knife4j 4.0.0
2.2.x~2.4.0 Knife4j 2.0.6 ~ 2.0.9 >=Knife4j 4.0.0
2.4.0~2.7.x >=Knife4j 4.0.0 >=Knife4j 4.0.0
>= 3.0 >=Knife4j 4.0.0 >=Knife4j 4.0.0

Swagger2规范OpenAPI3规范的说明

nife4j版本 Swagger2规范 OpenAPI3规范 说明
1.0~1.9.6 springfox 2.9.2 Knife4j的前身,名称为swagger-bootstrap-ui
1.9.6~2.0.5 springfox 2.9.2
2.0.6~2.0.9 springfox 2.10.5
3.0.0~3.0.3 springfox 3.0.3 过度版本,建议开发者不要使用
4.0.0~ springfox 2.10.5 >=springdoc-openapi 1.6.9 Swagger2规范稳定使用springfox2.10.5保持不变。开发者应该尽早迁移到OpenAPI3规范上来,请参考4.x升级文档

三、使用

1.引入依赖

  1. <dependency>
  2. <groupId>com.github.xiaoymin</groupId>
  3. <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
  4. <version>4.3.0</version>
  5. </dependency>

2.编写配置类

  1. package com.mcode.knife4jdemo.config;
  2. import io.swagger.v3.oas.models.OpenAPI;
  3. import io.swagger.v3.oas.models.info.Contact;
  4. import io.swagger.v3.oas.models.info.Info;
  5. import io.swagger.v3.oas.models.info.License;
  6. import org.springdoc.core.models.GroupedOpenApi;
  7. import org.springframework.context.annotation.Bean;
  8. import org.springframework.context.annotation.Configuration;
  9. /**
  10. * ClassName: Knife4jConfig
  11. * Package: com.mcode.knife4jdemo.config
  12. * Description:
  13. *
  14. * @Author: robin
  15. * @Version: v1.0
  16. */
  17. @Configuration
  18. public class Knife4jConfig {
  19. @Bean
  20. public GroupedOpenApi adminApi() { // 创建了一个api接口的分组
  21. return GroupedOpenApi.builder()
  22. .group("admin-api") // 分组名称
  23. .pathsToMatch("/admin/**") // 接口请求路径规则
  24. .build();
  25. }
  26. @Bean
  27. public OpenAPI openAPI(){
  28. return new OpenAPI()
  29. .info(new Info()
  30. .title("Knife4j标题")
  31. .description("Knife4j说明")
  32. .version("v1")
  33. .contact(new Contact().name("robin").email("robin@gmail.com"))
  34. .license(new License().name("Apache 2.0").url("http://springdoc.org"))
  35. );
  36. }
  37. }

3.编写User类用作模型

  1. package com.mcode.knife4jdemo.entity;
  2. import io.swagger.v3.oas.annotations.media.Schema;
  3. /**
  4. * ClassName: User
  5. * Package: com.mcode.knife4jdemo.entity
  6. * Description:
  7. *
  8. * @Author: robin
  9. * @Version: v1.0
  10. */
  11. @Schema(description = "用户实体")
  12. public class User {
  13. @Schema(description = "用户名称")
  14. private String userName;
  15. @Schema(description = "密码")
  16. private String password;
  17. @Schema(description = "邮箱")
  18. private String email;
  19. @Schema(description = "年龄")
  20. private int age;
  21. public String getUserName() {
  22. return userName;
  23. }
  24. public void setUserName(String userName) {
  25. this.userName = userName;
  26. }
  27. public String getPassword() {
  28. return password;
  29. }
  30. public void setPassword(String password) {
  31. this.password = password;
  32. }
  33. public String getEmail() {
  34. return email;
  35. }
  36. public void setEmail(String email) {
  37. this.email = email;
  38. }
  39. public int getAge() {
  40. return age;
  41. }
  42. public void setAge(int age) {
  43. this.age = age;
  44. }
  45. public User() {
  46. }
  47. public User(String userName, String password, String email, int age) {
  48. this.userName = userName;
  49. this.password = password;
  50. this.email = email;
  51. this.age = age;
  52. }
  53. }

4.编写控制器

  1. package com.mcode.knife4jdemo.controller;
  2. import com.mcode.knife4jdemo.entity.User;
  3. import io.swagger.v3.oas.annotations.Operation;
  4. import io.swagger.v3.oas.annotations.Parameter;
  5. import io.swagger.v3.oas.annotations.enums.ParameterIn;
  6. import io.swagger.v3.oas.annotations.tags.Tag;
  7. import org.springframework.web.bind.annotation.*;
  8. /**
  9. * ClassName: IndexController
  10. * Package: com.mcode.knife4jdemo.controller
  11. * Description:
  12. *
  13. * @Author: robin
  14. * @Version: v1.0
  15. */
  16. @RestController
  17. @Tag(name = "首页")
  18. @RequestMapping("/admin/index")
  19. public class IndexController {
  20. @Operation(summary = "获取用户")
  21. @GetMapping("/getUser")
  22. public User getUser( @Parameter(name = "userName",description = "用户名称",in = ParameterIn.QUERY)String userName) {
  23. return new User(userName, "123456", "123@qq.com", 18);
  24. }
  25. @Operation(summary = "新增用户")
  26. @PostMapping("/addUser")
  27. public Boolean addUser(@RequestBody User user) {
  28. return true;
  29. }
  30. }

SpringDoc注解具体可看:https://www.cnblogs.com/vic-tory/p/17690501.html

四、效果图

首页

image

控制器

image

原文链接:https://www.cnblogs.com/vic-tory/p/17773531.html

 友情链接:直通硅谷  点职佳  北美留学生论坛

本站QQ群:前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

W3xue 的所有内容仅供测试,对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接(目前9元/月)请联系QQ:27243702 沸活量
皖ICP备17017327号-2 皖公网安备34020702000426号