鱼和熊掌不可兼得:Spring boot3,Swagger3(使用Mybatis-Plus搭建框架)

文章写于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文件,注意里面被注释的内容,被注释的内容是第二次升级需要用到的代码.具体代码如下:(以下的代码是本篇文章的完整代码)

    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        3.1.1
         
    
    com.flamelp
    demo
    0.0.1-SNAPSHOT
    MP_Redis_SpringDoc
    MP_Redis_SpringDoc
    
        17
    
    

        
            org.springframework.boot
            spring-boot-starter-data-redis
        
        
            redis.clients
            jedis
        
        
            org.springframework.boot
            spring-boot-starter-cache
        
        
            org.springframework.boot
            spring-boot-starter-thymeleaf
        
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            org.mybatis.spring.boot
            mybatis-spring-boot-starter
            3.0.2
        

        
            com.mysql
            mysql-connector-j
            runtime
        
        
            org.projectlombok
            lombok
            true
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        
        
            org.mybatis.spring.boot
            mybatis-spring-boot-starter-test
            3.0.2
            test
        

        
            com.baomidou
            mybatis-plus-boot-starter
            3.5.3.1
        
        
            com.baomidou
            mybatis-plus-generator
            3.5.3.1
        
        
            org.apache.velocity
            velocity-engine-core
            2.3
        


        
            org.springdoc
            springdoc-openapi-starter-webmvc-ui
            2.0.4
        







    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                
                    
                        
                            org.projectlombok
                            lombok
                        
                    
                
            
        
    

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的配置

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.0.4

2.在实体类,Controll类中添加注解,注解说明如下:

OpenAPI注解

注解	说明
@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;

/**
 * 

 * 用户表 前端控制器
 * 
 *
 * @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 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
 showAddress() {
        List
 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_cn

3.其它的不需要做修改,包括类里面的注解一个都不需要改.不过访问路径不同了.http://localhost:xxxx/doc.html#/home

原来的http://localhost:XXXX/swagger-ui/index.html   路径仍然可以访问.但是很明显doc.html访问更加的清晰.而且描述也更加的具体.