Swagger系列：SpringBoot3.x中使用Knife4j

Posted on by hackdl

目录
  • 一、简介
  • 二、版本说明
  • 三、使用
  • 四、效果图

一、简介

官网：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 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.引入依赖

		
			com.github.xiaoymin
			knife4j-openapi3-jakarta-spring-boot-starter
			4.3.0

2.编写配置类

package com.mcode.knife4jdemo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * ClassName: Knife4jConfig
 * Package: com.mcode.knife4jdemo.config
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@Configuration
public class Knife4jConfig {
    @Bean
    public GroupedOpenApi adminApi() {      // 创建了一个api接口的分组
        return GroupedOpenApi.builder()
                .group("admin-api")         // 分组名称
                .pathsToMatch("/admin/**")  // 接口请求路径规则
                .build();
    }
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info()
                        .title("Knife4j标题")
                        .description("Knife4j说明")
                        .version("v1")
                        .contact(new Contact().name("robin").email("robin@gmail.com"))
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );

    }
}

3.编写User类用作模型

package com.mcode.knife4jdemo.entity;

import io.swagger.v3.oas.annotations.media.Schema;

/**
 * ClassName: User
 * Package: com.mcode.knife4jdemo.entity
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户名称")
    private String userName;
    @Schema(description = "密码")
    private String password;
    @Schema(description = "邮箱")
    private String email;

    @Schema(description = "年龄")
    private int age;


    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public User() {
    }

    public User(String userName, String password, String email, int age) {
        this.userName = userName;
        this.password = password;
        this.email = email;
        this.age = age;
    }
}

4.编写控制器

package com.mcode.knife4jdemo.controller;

import com.mcode.knife4jdemo.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

/**
 * ClassName: IndexController
 *服务器托管网 Package: com.mcode.knife4jdemo.controller
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@RestController
@Tag(name = "首页")
@RequestMapping("/admin/index")
public class IndexController {
    @Operation(summary = "获取用户")
    @GetMapping("/getUser")
    public User getUser( @Parameter(name = "userName",description = "用户名称",in = ParameterIn.QUERY)String userName) {
        return new User(userName, "123456", "123@qq.com", 18);
    }
    @Operation(summary = "新增用户")
    @PostMapping("/addUser")
    public Boolean addUser(@RequestBody  User user) {
        return true;
    }
}

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

四、效果图

首页

控制器

服务器托管，北京服务器托管，服务器租用 http://www.fwqtg.net
机房租用，北京机房租用，IDC机房托管， http://www.fwqtg.net

相关推荐: JDBC连接GaussDB云数据库操作示例

目录 一、实验环境 二、登录华为云创建测试库表 1、登录GaussDB云数据库 2、建库、建表,用于测试 3、新增普通角色（用户）用于登录及访问测试（可选） 4、获取对应的公网IP 三、创建java工程 1、创建java工程 2、添加jar包 3、编辑Java…

服务器托管，北京服务器托管，服务器租用，机房机柜带宽租用

服务器托管

咨询：董先生

电话13051898268 QQ/微信93663045！

上一篇:
下一篇: