程序员经验分享-hwhale

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

2023-11-10

文章写于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类中添加注解,注解说明如下:

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;

/**
 * <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_cn

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

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

 

本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)

SSM

Spring

spring boot

Java

MyBatis

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

随机推荐

热门标签