Springboot整合Swagger2（3.0.0版本）

天行健，君子以自强不息；地势坤，君子以厚德载物。

---

每个人都有惰性，但不断学习是好好生活的根本，共勉！

---

文章均为学习整理笔记，分享记录为主，如有错误请指正，共同学习进步。

---

Swagger2简介

swagger2是一个基于OpenAPI（OpenAPI Specification，OAS）构建的开源工具，提供对REST API文档的一些有效帮助。简而言之就是将项目中的controller类和方法通过注解方式生成文档展现出来。
swagger包含三个内容：

• swagger codegen：通过OpenApi规范定义任何api生成服务器存根和客户端sdk来简化构建过程
• swagger editor： 浏览器编辑器，用来编写OpenApi规范
• swagger ui： 可以在浏览器上查看并操作REST API

两个组件：

• springfox-swagger2： 这个组件用于自动生成描述API的json文件
• springfox-swagger-ui： 将描述API的json解析并展现

3.0.0版本比2.9.2更新了什么：

• 支持spring5，Webflux（仅支持请求映射，不支持功能端点）
• 支持spring integration
• 支持starter自动配置（springfox-boot-starter）
• 支持自动完成文档化配置
• 支持OpenApi 3.0.3
• 支持兼容2.0版本
• 兼容性说明（Java8及以上版本，spring5.x及以上版本，springboot2.2以上版本）

---

开发环境：

JDK版本：1.8
maven版本：3.9.0
开发工具：IDEA社区版ideaIC-2018.3
项目框架：spring boot 版本为 2.5.6 springboot搭建传送门

实现步骤说明

1. 搭建项目

创建maven项目引入springboot依赖
项目包框架如下
注：这里使用3.0.0版本的swagger，不需要配置SwaggerConfig配置类

2. 引入依赖

引入spring boot和swagger2依赖
注：这里可能因为版本兼容问题，我试了很多个版本都会出现报错，目前来看2.5.6版本是可以和swagger的3.0.0版本配合使用的
注：其他版本需要配置一个参数，传送门-->：spring boot整合swagger3.0.0版本兼容配置

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
<!--            <version>2.5.6</version>-->
<!--            <version>2.6.3</version>-->
<!--            <version>2.6.5</version>-->
            <version>2.7.3</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.26</version>
        </dependency>

3. application.yml

spring:
  mvc:
    pathmatch:
      #这里配置的这个参数是为了解决spring boot和swagger版本不兼容的问题
      matching-strategy: ant_path_matcher

4. 创建启动类

注：这里发现一个现象，正常是需要在启动类上添加@EnableOpenApi注解来开启功能的，但是我在项目中不用这个注解，且请求接口类上也不加这个注解，启动项目后也是可以看到接口文档的，发现有没有这个注解都是一样的。
SwaggerApplication.java

package com.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

/**
 * @ClassDescription:
 * @Author：李白
 * @Date：2023/5/22 14:57
 */
//@EnableOpenApi//不用好像也可以
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

5. 创建实体类

UserInfo.java

package com.swagger.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * @ClassDescription:
 * @Author：李白
 * @Date：2023/5/22 16:00
 */
@ApiModel(value = "用户实体类", description = "用户实体类描述")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserInfo {
    @ApiModelProperty(name = "id", value = "学生姓名", example = "12345")
    private Integer id;
    @ApiModelProperty(name = "username", value = "用户账号", example = "12345")
    private String username;
    @ApiModelProperty(name = "password", value = "用户密码", example = "12345")
    private String password;
}

6. 创建控制类

UserController.java

package com.swagger.controller;

import com.swagger.entity.UserInfo;
import com.swagger.vo.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @ClassDescription:
 * @Author：李白
 * @Date：2023/5/22 15:01
 */
@Api(value = "用户数据操作类",tags = {"用户数据操作接口"})
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 模拟数据库
     */
    static Map<Integer, UserInfo> users = new HashMap<>();

    /**
     * 模拟自增主键
     */
    static Integer id = 1;

    /**
     * 查询所有数据
     * @return
     */
    @ApiOperation(value = "查询用户数据", notes = "查询所有用户数据")
    @GetMapping
    public ResponseResult getUserInfoList(){
        List<UserInfo> userInfoList = new ArrayList<>(users.values());
        return ResponseResult.success(userInfoList);
    }

    /**
     * 根据id查询数据
     * @param id
     * @return
     */
    @ApiOperation(value = "根据id查询数据", notes = "根据id查询数据信息")
//    @ApiParam(name = "id", value = "用户id", required = true)
//    @ApiImplicitParam(name = "id", value = "用户id", dataType = "Integer", paramType = "query",example = "libai123", required = true)
    @GetMapping("/{id}")
    public ResponseResult getUserInfoById(@PathVariable("id") Integer id){
        return ResponseResult.success(users.get(id));
    }

    /**
     * 新增数据
     * @param userInfo
     * @return
     */
//    @ApiIgnore//用在类或方法上，可以不被swagger显示在页面上
//    @ApiResponses({@ApiResponse(code = 200, message = "ok", response = UserInfo.class)})
    @ApiOperation(value = "新增数据", notes = "新增用户数据信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true),
            @ApiImplicitParam(name = "password", value = "用户密码", required = true)
    })
    @PostMapping
    public ResponseResult postUserInfo(UserInfo userInfo){
        userInfo.setId(id++);
        users.put(userInfo.getId(),userInfo);
        System.out.println(users);
        return ResponseResult.success();
    }

    /**
     * 更新数据
     * @param userInfo
     * @return
     */
    @ApiOperation(value = "更新数据", notes = "更新用户数据")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true),
            @ApiImplicitParam(name = "password", value = "用户密码", required = true)
    })
    @PutMapping
    public ResponseResult putUserInfo(UserInfo userInfo){
        UserInfo userInfo1 = users.get(userInfo.getId());
        userInfo1.setPassword(userInfo.getPassword());
        userInfo1.setUsername(userInfo.getUsername());
        return ResponseResult.success(userInfo1);
    }

    /**
     * 删除数据
     * @param id
     * @return
     */
    @ApiOperation(value = "删除数据", notes = "根据id删除用户数据")
    @ApiImplicitParam(name = "id", value = "用户id", required = true)
    @DeleteMapping("/{id}")
    public ResponseResult deleteUserInfo(@PathVariable("id") Integer id){
        users.remove(id);
        return ResponseResult.success();
    }




}

7. 添加swagger2相关注解

在实体类和控制类上添加相应的注解
注解介绍如下：

• 在主类（程序启动类）上添加注解@EnableOpenApi开启swagger
• 在controller类上添加@Api
• 在实体类上添加@ApiModel
• 实体类（对象）属性添加@ApiModelProperty
• 接口参数描述使用@ApiImplicitParams
• 接口响应使用@ApiResponses
• 接口忽略（可不在网页中显示）使用@ApiIgnore

8. 查看生成的文档

启动项目
浏览器中访问地址（端口号可根据自己的项目端口更改，默认为8080）

http://localhost:8080/swagger-ui/index.html

（3.0.0版本为上面这个地址，2.9.2的老版本则为http://localhost:8080/swagger-ui.html）
如下图

---