文章写于2023年7月1日,目前使用的配置尽量用最新的,如果晚于这个日期很久,请参考新的配置.
使用MyBatis plus搭建框架后使用swagger或者采用的Spring 3后使用swagger 3,启动项目出现如下错误:Type javax.servlet.http.HttpServletRequest not present
其根本原因是spring3目前不支持swagger产生的问题.解决方法有两种一种改为spring2,另外就是找一个swagger的代替品.
作为一个倔强的程序员(我一直认为这个是程序员应该有的良好品质),是绝对不会放弃新版本的spring3的,所以只能更换swagger了.
接下来我们将对程序进行两次升级.下面将用一个案例来说明.别担心,很简单.
1.创建两张MySql表
CREATE TABLE `address` (
`id` int NOT NULL AUTO_INCREMENT COMMENT '主键:用户地址编号',
`usersId` int NULL COMMENT '外键:用户编号',
`tel` varchar(20) NULL COMMENT '电话',
`location` varchar(200) NULL COMMENT '详细地址',
`recipient` varchar(20) NULL COMMENT '收件人',
`locationName` varchar(20) NULL COMMENT '命名的收件地址',
`deleted` tinyint NULL COMMENT '逻辑删除',
PRIMARY KEY (`id`)
);
CREATE TABLE `users` (
`id` int NOT NULL AUTO_INCREMENT COMMENT '主键:用户编号',
`userName` varchar(20) NULL COMMENT '姓名',
`password` varchar(20) NULL COMMENT '登录密码',
`age` int NULL COMMENT '年龄',
`email` varchar(50) NULL COMMENT '邮箱,登录名',
`deleted` tinyint NULL COMMENT '逻辑删除',
PRIMARY KEY (`id`)
) COMMENT = '用户表';
ALTER TABLE `address` ADD CONSTRAINT `fk_address_users_1` FOREIGN KEY (`usersId`) REFERENCES `users` (`id`);
2.创建好项目,搭建项目框架,本次仍然是使用Spring boot ,MyBatis Plus进行项目搭建,先添加pom文件,注意里面被注释的内容,被注释的内容是第二次升级需要用到的代码.具体代码如下:(以下的代码是本篇文章的完整代码)
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.1.1</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.flamelp</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>MP_Redis_SpringDoc</name>
<description>MP_Redis_SpringDoc</description>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<!-- redis,jedis,cache,spring boot web,thymeleaf,mybatis-spring,lombok-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<dependency>
<groupId>redis.clients</groupId>
<artifactId>jedis</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-cache</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.mybatis.spring.boot</groupId>
<artifactId>mybatis-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.mybatis.spring.boot</groupId>
<artifactId>mybatis-spring-boot-starter-test</artifactId>
<version>3.0.2</version>
<scope>test</scope>
</dependency>
<!--mp,mp代码生成器,模板-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>3.5.3.1</version>
</dependency>
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-generator</artifactId>
<version>3.5.3.1</version>
</dependency>
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity-engine-core</artifactId>
<version>2.3</version>
</dependency>
<!-- 第一次升级使用springDoc 代替swagger-->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.4</version>
</dependency>
<!--第二次升级使用knife4j,里面包含了第一次升级使用springDoc-->
<!-- <dependency>-->
<!-- <groupId>com.github.xiaoymin</groupId>-->
<!-- <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>-->
<!-- <version>4.1.0</version>-->
<!-- </dependency>-->
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
</plugins>
</build>
</project>
3.使用MyBatis Plus生成代码框架,这部分内容略,可以看我另外一篇文章:
MyBaits-Plus使用redis作为缓存的另外一种方法_flame.liu的博客-CSDN博客
这里需要注意的是MyBatis Plus的最新版已经支持springDoc了,这里需要做一些小的改动:
在MyBatis Plus进行全局配置的时候将enableSwagger() 改为 enableSpringdoc(),这样MP将自动在实体类上创建好SpringDOC的注解,省下很多事情.
第一次升级,使用功能更加强大的SpringDoc代替现有的Swagger,虽然SpringDoc也可以叫做Swagger.
1.在pom文件中去掉swagger的配置,添加springDOC的配置
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.4</version>
</dependency>2.在实体类,Controll类中添加注解,注解说明如下:
| 注解 | 说明 |
| @Schema | 标注在实体和实体的属性上面,如果使用MyBatis-Plus会自动给你加上 |
| @Tag(name = “接口类描述”) | 标注在controller上,用来描述类的作用. |
| @Operation(summary =“接口方法描述”) | 标注在controller的方法上,用来描述方法的作用 |
| @Parameter(description=“参数描述”) | 标注在controller的方法上,用来描述方法的参数 |
| @Parameters | 标注在controller的方法上,用来描述方法的多个参数 |
| @Parameter(hidden = true) 、@Operation(hidden = true)@Hidden | 排除api,一般不用到. |
接下来我们从具体使用来看注解的用法
3.实体类具体代码.(由MP自动生成)
@TableName("users")
//mybatis plus会自动添加@Schema主键,前提条件是你在数据库的表和列中添加了相应的注释
@Schema(name = "Users", description = "用户表")
public class Users implements Serializable {
private static final long serialVersionUID = 1L;
@Schema(description = "主键:用户编号")
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
}以上是代码片段,主要由MP自动生成,
4.controller类具体代码,这里写了两个类和不同的方法做对比.
先是UsersController类
import com.flamelp.demo.entity.Users;
import com.flamelp.demo.service.IUsersService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.ModelAndView;
import java.util.List;
/**
* <p>
* 用户表 前端控制器
* </p>
*
* @author flamelp. 仅用于教学使用
* @since 2023-07-01
*/
@RestController
@RequestMapping("/demo/users")
@Tag(name="UsersController",description = "操作用户信息的接口")
public class UsersController {
@Resource
private IUsersService usersService;
@Tag(name = "createData",description = "初始化页面数据")
@Parameter(name = "modelAndView",description = "action传递过来的modelView")
private void createData(ModelAndView modelAndView){
List<Users> usersList = usersService.list();
//页面初始化时,添加所有数据并显示
modelAndView.addObject("usersList",usersList);
}
@RequestMapping("index")
@Operation(summary="index",description = "默认显示所有用户信息")
public ModelAndView index(){
ModelAndView modelAndView = new ModelAndView("index");
return modelAndView;
}
@RequestMapping("search")
@Operation(summary="search",description = "根据id搜索用户信息")
@Parameter(name="search",description = "需要查找的用户编号")
@ApiResponse(description = "返回查询到的用户")
public Users search(int id){
Users user = usersService.selectById(id);
return user;
}
}这里需要注意的是private方法,返回ModelAndView的方法是不会出现在测试里面的.另外也可以观察到这两个方法使用的是@RequestMapping注解,所以在测试的时候可以用到多种方式进行测试,先不急,后面会遇到.
为了做对比,还有一个AddressController类.
import com.flamelp.demo.entity.Address;
import com.flamelp.demo.service.IAddressService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/demo/address")
@Tag(name = "AddressController", description = "地址管理")
public class AddressController {
@Resource
private IAddressService addressService;
@GetMapping({"list"})
@Operation(summary = "showAddress", description = "查找并显示所有地址")
@ApiResponse(description = "所有用户信息")
public List<Address> showAddress() {
List<Address> addresses = this.addressService.list();
return addresses;
}
@PostMapping("addAddress")
@Operation(summary = "addAddress", description = "添加地址信息")
@Parameter(name = "addresses", description = "需要添加的地址信息")
public Address addAddress(Address addresses) {
return this.addressService.add(addresses);
}
}这里使用的是@GetMapping和@PostMapping注解.后面截图你会看到不一样的地方.
接下来是启动.在地址栏输入http://localhost:XXXX/swagger-ui/index.html xxxx是你指定的端口
打开的页面是:
上图显示的是两个controll和实体类.可以看到UsersController类的私有方法和返回ModelAndView的方法没有显示在这里,同时标注了@RequestMapping注解的方法有7种测试方法.
如果我们有多个controller,并且方法也很多的时候,这个页面就会显得凌乱,那么有什么好办法吗?这就是我们的第二次升级.
第二次升级:使用knife4j增强工具,别急,改动很少.
1.在pom中去掉,springdoc-openapi-starter-webmvc-ui的配置,并取消knife4j-spring-boot-starter 和 knife4j-openapi3-jakarta-spring-boot-starter的注释,也就是启用这两个.代码在前面已经给了.
btw:knife4j 包含了springdoc
2.配置application.yml
# springdoc-openapi 配置
springdoc:
swagger-ui:
#springdoc的访问路径
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
#需要扫描的包,这里需要改成你自己的.
packages-to-scan: com.flamelp.demo
knife4j:
enable: true
setting:
language: zh_cn3.其它的不需要做修改,包括类里面的注解一个都不需要改.不过访问路径不同了.http://localhost:xxxx/doc.html#/home
原来的http://localhost:XXXX/swagger-ui/index.html 路径仍然可以访问.但是很明显doc.html访问更加的清晰.而且描述也更加的具体.
