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

---

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

---

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

---

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 = "查询所有用户数据")@GetMappingpublic 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)})@PostMappingpublic 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)})@PutMappingpublic 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）
如下图

---