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

记录成长java

于 2024-05-21 14:47:45 发布

阅读量1.2k

点赞数 20

文章标签： spring boot intellij-idea

本文链接：https://blog.csdn.net/qq_74947724/article/details/139076219

版权

knife4j的使用

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项目并导入需要的坐标

   <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.0</version>
    </parent>
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <druid.version>1.2.1</druid.version>
        <mysql.version>8.0.32</mysql.version>
        <mybatisPlus.version>3.5.4</mybatisPlus.version>
        <knife4j.version>4.4.0</knife4j.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>${druid.version}</version>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>${mysql.version}</version>
        </dependency>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>${mybatisPlus.version}</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </dependency>

    </dependencies>

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<Student> {
}

1.6编写service层代码

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

public interface StudentService extends IService<Student> {
}


@Service
public class StudentServiceImpl extends ServiceImpl<StudentMapper, Student> implements StudentService {
}

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

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

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

@Data
public class Result <T>{
    private Integer code; //0代表成功，1代表失败
    private T data;
    private String message;

    public static <T>  Result<T>   success(T data){
        Result<T> result = new Result<>();
        result.setCode(0);
        result.setData(data);
        return result;
    }
    public static <T>  Result<T>   success(){
        Result<T> result = new Result<>();
        result.setCode(0);
        return result;
    }
    public static <T> Result<T> error(String message){
        Result<T> 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<List<Student>> findAll(){
        log.info("查询所有学生信息");
        List<Student> list = studentService.list();
        return Result.success(list);
    }
}

2.配置knife4j

前提要求：jdk>=17,springboot3

2.1引入坐标

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

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文档的时候需要输入账号和密码，

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<List<Student>> findAll(){
        log.info("查询所有学生信息");
        List<Student> 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<List<Student>> findAll(){
        log.info("查询所有学生信息");
        List<Student> 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("删除失败");
    }
}