【SpringBoot】Swagger 接口工具

目标

• 了解作用
• 了解前后端分离
• 在SpringBoot 中集成

Swagger简介

前后端分离

典型：Vue

SpringBoot+Vue/React 经典 ；

• 后端时代：前端管理 只是静态页面，后期引申为JSP
• 前后端分离：
  • 后端：控制层，服务层，数据访问层
  • 前端：控制层，视图层

前后端通过api进行交互

前后端相对对立，松耦合度

前后端部署到不同的服务器上，与微信小程序同理

产生的问题

前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

• 定义一个 schema 计划，及时跟踪降低风险；
• 制定word开发计划文档；
• 前期测试后端接口 使用 postman，依赖于外部管理；
• Swagger出现，一个api框架

Swagger

• 一个比较流行的API框架；
• Restful API文档在线自动生成器，API和API定义同步更新；
• 直接运行，在线测试API
• 支持多种语言
• 官网：https://swagger.io/
• 中文网站：https://swagger.org.cn/docs/
• 替代：ApiFox

SpringBoot集成Swagger

项目驱动

1. 新建一个SpringBoot的web项目；
2. 导入依赖：SpringBoot-web、Swagger、Swagger-ui

Spring Boot 3.5.4 版本，由于 Springfox（传统 Swagger 实现）已不兼容 Spring Boot 3.x，必须改用 SpringDoc OpenAPI（支持 OpenAPI 3.0 规范）；

3. Spring Boot 2.*时代的依赖

在 Spring Boot 3.5.4 中集成 Swagger 需要使用 SpringDoc OpenAPI（替代已停止维护的 Springfox），之前使用的Docket也已经被废止，换成了GroupedOpenApi和OpenAPIBean的组合

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency><!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version>
</dependency>

4. 新使用的依赖是 springdoc-openapi-starter-webmvc-ui，不需要使用Swagger-ui
5. 编写一个Hello程序，测试后开始swagger学习；

具体流程

导入依赖springdoc-openapi-starter-webmvc-ui

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version> <!-- 兼容 Spring Boot 3.5.4 的最新稳定版 -->
</dependency>

配置swagger的config

1. 编写Config配置文件，配置swagger的内容显示

@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("新接口网页").version("2.0").description("基于 OpenAPI 3.0 的配置"));}
}

2. 项目启动成功

3. 访问swagger UI页面 [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html),页面显示正常;

4. 访问http://localhost:8080/v3/api-docs ，查看完整的 OpenAPI 3.0 规范 JSON;

5. 对比我们的Controller请求,内容显示无误

分组：定义自定义模块和扫描路径

1. 注入GroupedOpenApi，显示我们自定义模块和分组扫描的路径

@Bean
public GroupedOpenApi indexApi() {return GroupedOpenApi.builder().group("默认").pathsToMatch("/**") // 匹配接口路径.build();
}@Bean
public GroupedOpenApi userApi() {return GroupedOpenApi.builder().group("用户模块").pathsToMatch("/api/users/**") // 匹配接口路径.build();
}

2. 页面显示，因为使用的@RequestMapping，所以所有的请求都显示了；

2.0（Docket） 和 3.0 的区别

实体类的扫描

1. 编写Controller，实体类，查看swagger-ui的页面

@RestController
public class HelloController {@PostMapping("/hello")public String hello() {return "Greetings from Spring Boot!";}@GetMapping("/user")public User userList() {return new User();}
}

public class User {private String name;private String password;private String sex;}

2. 修改实体类，加上@Schema，添加描述信息

package com.demo.pojo;import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;@Data
@Schema(description = "用户信息")
public class User {@Schema(description = "用户名称")private String name;@Schema(description = "用户密码")private String password;@Schema(description = "用户性别")private String sex;public User() {}public User(String name, String password, String sex) {this.name = name;this.password = password;this.sex = sex;}
}

3. 测试页面，内容显示，方便前后端互相分工操作开发内容；

swagger的其他配置

1. Java配置，同上，使用@Bean的方式注入，配置一个@Conguration；
2. yaml配置；

springdoc:api-docs:enabled: true # 配置swagger是否启动path: /v3/api-docs # 规范 JSON的资源路径swagger-ui:path: /swagger-ui.html packages-to-scan:  # 基础包扫描- com.example.controller - com.example.apipaths-to-match:    # 路径模式匹配- /api/**- /public/**paths-to-exclude:  # 路径排除- /internal/**

3. 判断当前的环境是什么，如果和提前定义的swagger环境相同，则为true，开启swagger，反则关闭。

4. Swagger测试，Execute根据输入的Parameter进行测试，会直接相应之后的信息，类比Postman思考，差不多

总结

1. 可以通过Swagger对接口和属性等内容添加注释；
2. 接口文档会根据项目内容自动更新；
3. 可以直接启动项目进行在线测试；

Swagger的使用很方便，需要注意 在正式使用发布的时候一定要关闭Swagger，安全，节能，高效。

apifox感觉也很不错 ，https://apifox.com/