SpringBoot2.0+Mybatis整合Swagger3.0

前言

在写项目的时候，想到swagger3已经更新了，于是想着尝鲜使用下，的确省去了很多配置。

swagger3.0

之前项目中整合Swagger都是直接通过依赖springfox-swagger、springfox-swagger-ui两个jar包来实现的，最近发现springfox 3.0.0版本已经有了自己的SpringBoot Starter，使用起来更契合SpringBoot项目，非常方便，推荐给大家。

由于swagger2 只支持 1.X-2.5 ,按照趋势，可能会淘汰。

swagger3.0 支持springBoot2.2X 以上版本使用，但在2.6以上版本需要配置一些参数才能使用

整合步骤

1.引入依赖

pom.xml

          <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
            <!--排除自带的1.5.20版本-->
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- 使用1.5.22-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

2.编写配置类

@Configuration
public class SwaggerConfig {

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("API文档")
                .description("使用RestFul风格,创建人：Andrew")
                .termsOfServiceUrl("www.baidu.com")
                .version("version 1.0")
                .build();
    }

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.orm.mybatis.swagger3"))
                .paths(PathSelectors.any())
                .build();
    }
}

说明:

apis(RequestHandlerSelectors.basePackage(“com.orm.mybatis.swagger3”))这个包名一定是包含自己项目的controller包路径,否则swagger不生效

其余的选项根据实际情况设置即可

3.编写Controller层注解

package com.orm.mybatis.swagger3.controller;

import com.orm.mybatis.swagger3.entity.User;
import com.orm.mybatis.swagger3.serviceImpl.UserServiceImpl;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.List;

/**
 * (User)表控制层
 *
 * @author makejava
 * @since 2022-03-11 09:53:09
 */
@Api(tags = "测试例子")
@RestController
@RequestMapping("user")
public class UserController {
    /**
     * 服务对象
     */
    @Resource
    private UserServiceImpl userService;


    /**
     * 通过主键查询单条数据
     *
     * @param id 主键
     * @return 单条数据
     */
    @ApiOperation(value="用户查询", notes="根据ID查询用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path" ,dataTypeClass = Integer.class)
    @GetMapping("{id}")
    public ResponseEntity<User> queryById(@PathVariable("id") Integer id) {
        return ResponseEntity.ok(this.userService.queryById(id));
    }

    /**
     * 分页查询
     *
     * @return 查询结果
     */
    @ApiOperation(value = "用户列表",notes = "查询用户列表")
    @GetMapping("/all")
    public ResponseEntity<List<User>> queryAll() {
        return ResponseEntity.ok(userService.queryAll());
    }

    /**
     * 新增数据
     *
     * @param user 实体
     * @return 新增结果
     */
    @ApiOperation(value = "添加用户",notes = "创建新用户")
    @ApiImplicitParam(name = "user",value = "用户详细实体user",required = true ,dataType = "User")
    @PostMapping
    public ResponseEntity<User> add(@RequestBody User user) {
        System.out.println(user.toString());
        return ResponseEntity.ok(this.userService.insert(user));
    }

    /**
     * 编辑数据
     *
     * @param user 实体
     * @return 编辑结果
     */
    @ApiOperation(value = "更新用户",notes = "根据用户更新用户信息")
    @ApiImplicitParam(name = "user",value = "用户对象user",required = true,dataType = "User")
    @PutMapping
    public ResponseEntity<User> edit(@RequestBody User user) {
        return ResponseEntity.ok(this.userService.update(user));
    }

    /**
     * 删除数据
     *
     * @param id 主键
     * @return 删除是否成功
     */
    @ApiOperation(value = "删除用户",notes = "根据id删除指定用户")
    @ApiImplicitParam(name = "id",value = "用户ID",required = true,dataType = "Long",paramType = "query",dataTypeClass = Long.class)
    @DeleteMapping
    public ResponseEntity<Boolean> deleteById(Integer id) {
        return ResponseEntity.ok(this.userService.deleteById(id));
    }

}

Swagger中paramType
paramType：表示参数放在哪个地方
header–>请求参数的获取：
@RequestHeader(代码中接收注解)
query–>请求参数的获取：@RequestParam(代码中接收注解)
path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)
body -->请求参数的获取：@RequestBody(代码中接收注解) form（不常用）

常用注解：

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

注意
如果是SpringBoot更新至2.6.0以上，引发了这个bug。

SpringFox3 Failed to start bean ‘documentationPluginsBootstrapper’

方法一： 在配置文件里加一条
spring.mvc.pathmatch.matching-strategy=ant_path_matcher可解决

方法二：应用启动主类增加注解 @EnableWebMvc

4.访问路径

http://localhost:8088/swagger-ui/

注意事项
访问路径

新版本和旧版本文档访问路径发生了变化，新版本为：http://localhost:8080/swagger-ui/ ，旧版本为：http://localhost:8080/swagger-ui.html

5.项目地址

https://gitee.com/liuweiqiang12/springboot