当前位置：首页 > news >正文

Spring Boot 整合 Swagger 快速生成 API 文档的最佳实践

news 来源：原创 2025/6/16 7:35:56

在现代前后端分离的开发模式中，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