高端外贸网站建设免费seo快速排名工具
在现代前后端分离的开发模式中，API 文档扮演着至关重要的角色。清晰、准确、实时的 API 文档能够极大地提高前后端协作效率，减少沟通成本，并为后续的接口测试、维护提供便利。然而，手动编写和维护 API 文档是一项枯燥且容易滞后的工作。
这时，Swagger (OpenAPI) 登场了！Swagger 是一套用于构建、描述和可视化 RESTful API 的开源工具集。通过将 Swagger 与 Spring Boot 整合，我们可以实现在代码编写的同时自动生成 API 文档，并且提供一个交互式的 UI 界面供开发者和测试人员在线调试接口，极大地提升了开发效率和团队协作体验。
本文将详细介绍 Spring Boot 整合 Swagger 的最佳实践，从依赖引入到配置优化，帮助你快速构建专业、实时的 API 文档。
1. 为什么选择 Swagger？
- 自动化生成： 通过注解，从代码中自动生成 API 文档，避免手动编写。
- 交互式 UI： 提供 Swagger UI 界面，直观展示 API 信息，并可直接进行接口调试。
- 实时性： 随着代码的更新，API 文档也能实时同步，保证文档的准确性。
- 标准化： 基于 OpenAPI 规范，具有良好的通用性和扩展性。
- 前后端协作： 统一的文档标准，方便前后端开发人员理解和对接接口。
2. 引入 Swagger 依赖
在 Spring Boot 项目中集成 Swagger，我们通常会选择 springfox-boot-starter 这个库，它封装了 Swagger Core 和 Swagger UI 的相关功能，并提供了 Spring Boot 的自动配置。
在 pom.xml 中添加以下依赖：
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version> </dependency>
注意： Swagger 2 (即 springfox) 的最新版本是 3.0.0。如果你想使用 OpenAPI 3 规范，可以考虑使用 springdoc-openapi 项目，它提供了对 OpenAPI 3 的原生支持。本文主要以 springfox 为例进行讲解。
3. Swagger 配置类
为了更好地管理 Swagger 的配置，我们通常会创建一个独立的配置类。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi; // 新版本使用此注解
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@Configuration
@EnableOpenApi // 开启 Swagger 3 (OpenAPI 3.0) 支持
public class SwaggerConfig {@Bean