基于springboot3基本使用knife4j-openapi3-jakarta-spring-boot-starter

码农世界 2024-06-12 后端 102 次浏览 0个评论

knife4j的使用

1.创建springboot项目

1.1准备数据库数据
1.2创建maven项目并导入需要的坐标
1.3创建包和启动类
1.4编写配置文件，实体类
1.5编写mapper接口使其继承baseMapper
1.6编写service层代码
1.7编写统一返回结果代码和controller层代码
2.配置knife4j

2.1引入坐标
2.2 编写配置文件
2.3编写配置类
3.knif4j配置详解

3.1配置文件详解
3.2 配置类内容讲解
3.3常用注解介绍

3.4使用mybatis-plus完成增删改查

1.创建springboot项目

1.1准备数据库数据

# 创建数据库
create database if not exists student;
use student;
create table student(
    id int auto_increment primary key ,
    name varchar(20) comment '姓名',
    account varchar(10) comment '账号',
    password varchar(20) comment '密码',
    phone varchar(11) comment '联系方式',
    age int comment '年龄',
    gender varchar(1) comment '性别',
    stu_class varchar(10) comment '班级',
    id_deleted int default 0 comment '是否删除'
)comment '学生信息表';

1.2创建maven项目并导入需要的坐标

   
        org.springframework.boot
        spring-boot-starter-parent
        3.1.0
    
    
        17
        17
        UTF-8
        1.2.1
        8.0.32
        3.5.4
        4.4.0
    
    
        
            org.springframework.boot
            spring-boot-starter-test
        
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            com.alibaba
            druid-spring-boot-starter
            ${druid.version}
        
        
            mysql
            mysql-connector-java
            ${mysql.version}
        
        
            com.baomidou
            mybatis-plus-boot-starter
            ${mybatisPlus.version}
        
        
            org.projectlombok
            lombok
        
        
            org.junit.jupiter
            junit-jupiter-api
            test
        
        
            org.slf4j
            slf4j-api

1.3创建包和启动类

@SpringBootApplication
public class knife4jApplication {
    public static void main(String[] args) {
        SpringApplication.run(knife4jApplication.class,args);
    }
}

1.4编写配置文件，实体类

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/student
    username: root
    password: 311412
    type: com.alibaba.druid.pool.DruidDataSource
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true #开启驼峰命名与下滑线命名转换
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  #查看日记

@Data
@Builder
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Integer id;
    private String account;
    @TableField("nick_name")
    private String nickName;
    private String name;
    private String password;
    private String phone;
    private String gender;
    private Integer age;
    @TableLogic
    @TableField("id_delete")
    private Integer idDelete;
}

1.5编写mapper接口使其继承baseMapper

@Mapper
public interface StudentMapper extends BaseMapper {
}

1.6编写service层代码

编写service接口使其继承IService,编写service实现类使其实现service接口，继承ServiceImpl

public interface StudentService extends IService {
}
@Service
public class StudentServiceImpl extends ServiceImpl implements StudentService {
}

1.7编写统一返回结果代码和controller层代码

返回结果这里以json形式，code值里面0代表成功，1代表失败

{
  "code": 0,
  "data": [],
  "message": null
}

@Data
public class Result {
    private Integer code; //0代表成功，1代表失败
    private T data;
    private String message;
    public static   Result   success(T data){
        Result result = new Result<>();
        result.setCode(0);
        result.setData(data);
        return result;
    }
    public static   Result   success(){
        Result result = new Result<>();
        result.setCode(0);
        return result;
    }
    public static  Result error(String message){
        Result result = new Result<>();
        result.setMessage(message);
        result.setCode(0);
        return result;
    }
}

controller层代码，采取REST风格进行开发

REST（Representational State Transfer）风格的开发是一种用于网络应用的架构风格，广泛用于构建灵活、可扩展的Web服务。RESTful服务通常使用HTTP协议的标准方法来执行增删改查（CRUD）操作：

创建（Create） - 使用POST方法
读取（Read） - 使用GET方法
更新（Update） - 使用PUT或PATCH方法
删除（Delete） - 使用DELETE方法

@RestController
@RequestMapping("/student")
@Slf4j
public class StudentController {
    @Autowired
    private StudentService studentService;
    @GetMapping("/findAll")
    public Result> findAll(){
        log.info("查询所有学生信息");
        List list = studentService.list();
        return Result.success(list);
    }
}

2.配置knife4j

前提要求：jdk>=17,springboot3

2.1引入坐标

        
            com.github.xiaoymin
            knife4j-openapi3-jakarta-spring-boot-starter
            ${knife4j.version}

2.2 编写配置文件

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
    enabled: true
#  group-configs:
#    - group: "user"
#      paths-to-match: '/user/**'
#      packages-to-scan: 'com.nongda.controller'
#    - group: "manager"
#      paths-to-match: '/manager/**'
#      packages-to-scan: 'com.nongda.controller'
knife4j:
  enable: true
  setting:
    language: zh_cn
  basic:
    enable: true
    username: root
    password: 311412

2.3编写配置类

@Configuration
//@EnableKnife4j
public class Knife4jConfig {
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info()
                        .title("knife4j测试的接口文档")
                        .description("这是基于knife4j-openapi3-jakarta-spring-boot-starter的接口文档")
                        .version("1.0")
                        .contact(new Contact()
                                .name("zbk")
                                .email("891276734@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("springboot基础框架")
                        .url("http://localhost:8080"));
    }
//    下面是分组
    @Bean
    public GroupedOpenApi groupedOpenApi2(){
        return GroupedOpenApi.builder()
                .group("学生管理")
                .pathsToMatch("/student/**")
                .build();
    }
}

3.knif4j配置详解

配置完成后运行项目，访问http://localhost:8080/doc.html

3.1配置文件详解

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
    enabled: true
#  group-configs:
#    - group: "user"
#      paths-to-match: '/user/**'
#      packages-to-scan: 'com.nongda.controller'
#    - group: "manager"
#      paths-to-match: '/manager/**'
#      packages-to-scan: 'com.nongda.controller'
knife4j:
  enable: true
  setting:
    language: zh_cn
  basic:
    enable: true
    username: root
    password: 311412

springdoc.swagger-ui.path:设置Swagger UI界面的访问路径，如上面所示，则可以通过访问http://localhost:8080/swagger-ui.html,来查看和测试API文档。
tags-sorter和operations-sorter：这两个属性分别代表API标签和操作的排序方式，alpha表示按字母顺序进行排序。
api-docs.path:配置生成的OpenAPI3.0规范的JSON格式文档的访问路径。按上面配置意味着可以通过访问http://localhost:8080/v3/api-docs来查看生成的JSON文档。
api-docs.enabled:表示是否启用API文档的生成，true开启，false关闭
group-configs:创建API文档的多个分组，每个分组可以指定匹配的路径和扫描的java包。
group-configs.group：分组名称，
group-configs.paths-to-match:该分组的url
group-configs.packages-to-scan:该分组的控制器类所在的包
Knife4j配置部分
enable:表示启用Knife4j的增强功能，true开启，false关闭。在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解，也就是说开启后不用在配置类使用@EnableKnife4j注解。
knife4j.setting.language：Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)。
knife4j.basic.enable：对Knife4j提供的资源提供BasicHttp校验,保护文档
knife4j.basic.username：账号

knife4j.basic.password:密码，设置完账号密码后意味着访问ui文档的时候需要输入账号和密码，

基于springboot3基本使用knife4j-openapi3-jakarta-spring-boot-starter

3.2 配置类内容讲解

@Configuration
//@EnableKnife4j
public class Knife4jConfig {
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info()
//                        设置标题
                        .title("knife4j测试的接口文档")
//                        设置简述
                        .description("这是基于knife4j-openapi3-jakarta-spring-boot-starter的接口文档")
//                        设置版本
                        .version("1.0")
//                        设置联系方式
                        .contact(new Contact()
                                .name("zbk")
                                .email("891276734@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("springboot基础框架")
                        .url("http://localhost:8080"));
    }
//    下面是分组
    @Bean
    public GroupedOpenApi groupedOpenApi2(){
        return GroupedOpenApi.builder()
//                设置分组名称
                .group("学生管理")
//                分组url
                .pathsToMatch("/student/**")
//                该分组所在的包
                .packagesToScan("com.nongda.controller")
                .build();
    }
}

3.3常用注解介绍

@Tag : 作用于控制类上，**name属性用于描述控制类,**如
效果：

@Operation ：作用于控制类的方法上面，用于描述方法

    @GetMapping("/findAll")
    @Operation(summary = "查询所有学生")
    public Result> findAll(){
        log.info("查询所有学生信息");
        List list = studentService.list();
        return Result.success(list);
    }

效果：

@Parameter(hidden = true) 、@Operation(hidden = true)@Hidden ：这是用于排除或隐藏api；

@Schema:DTO实体DTO实体属性

没有添加上面两个注解效果：

@Data
@Builder
@TableName(value = "student")
public class Student {
    @TableId(type = IdType.AUTO)
    private Integer id;
    private String name;
    private String account;
    private String password;
    private String phone;
    private Integer age;
    private String gender;
    @TableField("stu_class")
    private String stuClass;
}

设置注解后：

@Data
@Builder
@TableName(value = "student")
public class Student {
    @TableId(type = IdType.AUTO)
    @Hidden//设置在文档里面隐藏
    private Integer id;
    @Schema(name = "姓名")
    private String name;
    @Schema(name = "账号")
    private String account;
    @Schema(name = "密码")
    private String password;
    @Schema(name = "联系方式")
    private String phone;
    @Schema(name = "年龄")
    private Integer age;
    @Schema(name = "性别")
    private String gender;
    @TableField("stu_class")
    @Schema(name = "班级")
    private String stuClass;
}

@Parameters ：对Controller 方法的参数进行参数描述

3.4使用mybatis-plus完成增删改查

@RestController
@RequestMapping("/student")
@Slf4j
@Tag(name = "学生管理模块")
public class StudentController {
    @Autowired
    private StudentService studentService;
    @GetMapping("/findAll")
    @Operation(summary = "查询所有学生")
    public Result> findAll(){
        log.info("查询所有学生信息");
        List list = studentService.list();
        return Result.success(list);
    }
    @PostMapping
    @Operation(summary = "添加学生信息")
    public Result add(@RequestBody Student student){
        log.info(student.toString());
        boolean save = studentService.save(student);
        return save?Result.success():Result.error("添加失败");
    }
    @PutMapping("/update/{id}")
    @Operation(summary = "修改学生信息")
    public Result update(@RequestBody Student student,@PathVariable Integer id){
        log.info(student.toString());
        log.info("id是：{}",id);
        student.setId(id);
        boolean flag = studentService.updateById(student);
        return flag?Result.success():Result.error("修改失败");
    }
    @DeleteMapping("/{id}")
    @Operation(summary = "删除学生信息")
    public Result delete(@PathVariable Integer id){
        log.info("id是：{}",id);
        boolean flag = studentService.removeById(id);
        return flag?Result.success():Result.error("删除失败");
    }
}

ui效果：

转载请注明来自码农世界，本文标题：《基于springboot3基本使用knife4j-openapi3-jakarta-spring-boot-starter》

码农世界 37815篇文章站点微博

每一天，每一秒，你所做的决定都会改变你的人生！

发表评论取消回复

评论列表（暂无评论，102人围观）参与讨论

码农世界管理员

基于springboot3基本使用knife4j-openapi3-jakarta-spring-boot-starter

knife4j的使用

1.创建springboot项目

1.1准备数据库数据

1.2创建maven项目并导入需要的坐标

1.3创建包和启动类

1.4编写配置文件，实体类

1.5编写mapper接口使其继承baseMapper

1.6编写service层代码

1.7编写统一返回结果代码和controller层代码

2.配置knife4j

2.1引入坐标

2.2 编写配置文件

2.3编写配置类

3.knif4j配置详解

3.1配置文件详解

3.2 配置类内容讲解

3.3常用注解介绍

3.4使用mybatis-plus完成增删改查

发表评论取消回复

还没有评论，来说两句吧...

文章目录

码农世界管理员

基于springboot3基本使用knife4j-openapi3-jakarta-spring-boot-starter

knife4j的使用

1.创建springboot项目

1.1准备数据库数据

1.2创建maven项目并导入需要的坐标

1.3创建包和启动类

1.4编写配置文件，实体类

1.5编写mapper接口使其继承baseMapper

1.6编写service层代码

1.7编写统一返回结果代码和controller层代码

2.配置knife4j

2.1引入坐标

2.2 编写配置文件

2.3编写配置类

3.knif4j配置详解

3.1配置文件详解

3.2 配置类内容讲解

3.3常用注解介绍

3.4使用mybatis-plus完成增删改查

Visual Studio 连接 MySQL 数据库 实现数据库的读写（C++）

[工业自动化-1]：PLC架构与工作原理

网络编程（六）TCP并发服务器

Vue3、Element Plus使用v-for循环el-form表单进行校验

Ceph: vdbench 测试ceph存储rbd块设备

linux如何部署前端项目和安装nginx

Windows OpenVPN的安装之服务器自动启动连接

服务器数据恢复—KVM虚拟机被误删除如何恢复虚拟磁盘文件？

发表评论取消回复

还没有评论，来说两句吧...

文章目录

Visual Studio 连接 MySQL 数据库实现数据库的读写（C++）