前言

来啦老铁！

最近在本地做个前后端，用于平时学习、练手，其中后端采用 SpringBoot3 系列~

• 今天记录：Spring Boot3 中集成 Swagger3~

学习路径

1. Swagger 简介；
2. 引入 Swagger 相关包；
3. 编写 Swagger 配置类；
4. Controller 上使用 Swagger Tag；
5. 修改项目配置文件 application.yml；
6. 使用 Swagger 前端；
7. Swagger 常用注解；

1. Swagger 简介；

以下简介摘抄自网络文章：
（原文链接：https://blog.csdn.net/YIDIY/article/details/124955352）

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：
1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说超级方便。

2.提供 Web 页面在线测试 API：Swagger 生成的文档支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

Swagger UI 提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

2. 引入 Swagger 相关包；

• 在项目 pom.xml 下增加如下包引用（项目使用 Maven）：

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.0.2</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
            <version>2.0.2</version>
        </dependency>

3. 编写 Swagger 配置类；

• 在项目 config 包下创建 SwaggerConfig.java 类，并编写代码如下：

package XXX.XXX.XXX.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info().title("SpringBoot Vue Test")
                        .description("SpringBoot+Vue Test Swagger debugging")
                        .version("v1"));
    }
}

4. Controller 上使用 Swagger Tag；

• 这里仅以 Tag 和 Operation 注解为例：

5. 修改项目配置文件 application.yml；

• 增加配置如下：

springdoc:
  swagger-ui.path: /swagger-ui.html

6. 使用 Swagger 前端；

• 启动应用，在浏览器访问 url：http://localhost:8080/swagger-ui/index.html

• 可以用页面上的 try it out 功能，试用我们的接口：

  
  

  

7. Swagger 常用注解；

• @Tag：用来描述一组操作的信息（一般用在controller控制层类上）。

• @OpenAPIDefinition：用于定义 OpenAPI 规范的元数据，包括文档信息、API基本信息和服务器信息等。

• @Info：用于定义 API 的信息，包括标题、描述、版本号等。

• @Server：用于定义 API 所在的服务器信息，包括 URL 和描述等。

• @Paths：用于定义 API 所有的路径，包括请求方法、请求参数、返回类型等。

• @Operation：用于定义 API 的操作信息，包括请求方法、请求路径、请求参数等。

• @Parameter：用于定义 API 的请求参数，包括参数名、类型、是否必须等。

• @RequestBody：用于定义 API 的请求体，包括请求内容类型、请求体参数等。

• @ApiResponse：用于定义 API 的响应信息，包括响应状态码、响应信息等。

• @Schema：用于定义 API 的请求和响应的数据模型，包括类型、属性等。

上述注解笔者当前并未全部使用过，后续有需要我们再补充~

怎么样，是不是超简单，这里遗留一个问题待广大网友共同思考：

• 如何在生产环境禁用 Swagger?

如果本文对您有协助，麻烦点赞、关注！

谢谢！