Spring Boot 与 Swagger 3.0 与 API 文档自动生成，一文带你搞定！

🏆本文收录于「滚雪球学SpringBoot」专栏(全网一个名)，手把手带你零基础入门Spring Boot，从入门到就业，助你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

环境说明：Windows 10 + IntelliJ IDEA 2021.3.2 + Jdk 1.8

概述

随着微服务架构的普及，RESTful API 已经成为系统间通信的核心方式。开发和维护高质量、清晰、易用的 API 文档变得尤为重要。手动编写和维护 API 文档不仅繁琐，而且容易出现与实际代码不一致的情况，增加了开发和维护的复杂度。因此，自动化生成 API 文档成为了开发者的最佳选择。

Swagger（现在的 OpenAPI 3.0）为我们提供了一个强大的工具，通过注解的方式，可以轻松地生成 API 文档，并且文档能够实时与代码同步。通过与 Spring Boot 集成，Swagger 可以在几乎不增加开发成本的情况下，为项目提供完善的 API 文档和交互式测试功能。

本文将深入探讨如何在 Spring Boot 项目中集成 Swagger 3.0（即 OpenAPI 3.0），自动生成 API 文档，并详细介绍如何配置、定制和管理这些文档。我们将涵盖如何通过 Swagger UI 提供可视化的 API 展示，如何为每个版本的 API 提供独立的文档，以及如何处理 API 文档的版本管理。📜🚀

目录

1. 🚀 Swagger 3.0 新特性及其在 Spring Boot 中的集成
2. 🛠️ 配置 Spring Boot 与 Swagger 3.0 自动生成 API 文档
3. ✍️ 在 Spring Boot 中为 API 接口添加自定义注解，完善 API 文档信息
4. 🌐 使用 Swagger UI 可视化展示 API 文档并提供交互式接口测试功能
5. 📅 管理 API 文档版本，为每个版本提供独立文档展示
6. 🧩 API 文档生成的最佳实践：清晰、易用与一致性
7. 💡 总结与展望
8. 🔍 延伸阅读与最佳实践

1. 🚀 Swagger 3.0 新特性及其在 Spring Boot 中的集成

Swagger 3.0 新特性

Swagger 3.0（OpenAPI 3.0）是现今最流行的 API 规范，它相比于 Swagger 2.0 引入了许多新的特性。其核心变化和优势包括：

• 组件化设计：Swagger 3.0 引入了 components 部分，集中管理 API 文档中复用的元素（如参数、请求体、响应体等），避免了冗余定义。

• 支持更复杂的响应模型：通过 allOf、oneOf 和 anyOf 等构造，Swagger 3.0 支持更复杂的响应模型，这对于接口响应可能是多个类型时非常有用。

• 改进的参数描述：Swagger 3.0 可以更加精确地描述接口的参数类型、默认值、格式、限制等信息，支持对查询参数、路径参数和请求头参数的详细描述。

• 增强的安全描述：支持 OAuth2、API 密钥等多种认证方式，提供更灵活的安全定义。

• 更丰富的响应描述：API 响应描述可以包含详细的返回码、响应体内容以及响应头等信息，允许开发者更好地定义响应结构。

在 Spring Boot 中集成 Swagger 3.0

在 Spring Boot 项目中集成 Swagger 3.0 可以通过 springdoc-openapi 来实现，它是官方推荐的与 Spring Boot 集成的工具，能够自动生成 OpenAPI 3.0 规范的 API 文档。

添加依赖

在 pom.xml 中添加 Swagger 3.0 相关依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.6</version>
</dependency>

通过这个依赖，您不仅可以生成 API 文档的 JSON 文件，还能集成 Swagger UI，展示和测试 API 文档。

配置 Swagger 3.0

集成之后，您可以在 Spring Boot 项目中自定义 OpenAPI 配置，例如设置文档的基本信息，如标题、描述、版本等。

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot API")
                        .version("v1")
                        .description("This is a sample Spring Boot RESTful API documentation generated with Swagger 3.0"));
    }
}

在此配置中，我们通过 @Bean 创建了一个 OpenAPI 对象，并为 API 文档定义了基本信息，如标题、版本号和描述等。

2. 🛠️ 配置 Spring Boot 与 Swagger 3.0 自动生成 API 文档

自动生成 API 文档

Spring Boot 与 Swagger 3.0 配合后，可以自动为所有标记了 @RestController 或 @Controller 注解的类生成 API 文档。Swagger 会扫描这些控制器，提取接口信息，自动生成相应的文档。

通过以下配置，您可以指定文档路径，并访问 Swagger UI 来查看和测试 API 文档。

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

这样，您可以通过访问 http://localhost:8080/swagger-ui.html 来查看自动生成的 Swagger UI 页面，访问 /v3/api-docs 获取 JSON 格式的 API 文档。

自定义 API 文档描述

您可以使用 Swagger 注解来为接口提供详细的描述，包括接口的功能、请求参数、响应体等信息。Spring Boot 提供了灵活的方式来定制接口文档，例如：

@Operation(summary = "Get all products", description = "Returns a list of all products")
@GetMapping("/products")
public List<Product> getAllProducts() {
    return productService.getAllProducts();
}

通过 @Operation 注解，您可以为接口方法提供简要说明，帮助使用者快速理解接口的功能。

请求体和响应体的说明

对于复杂的请求体和响应体，您可以使用 @RequestBody 和 @ApiResponse 注解来提供详细的说明：

@Operation(summary = "Create a new product", description = "Creates a new product in the database")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Successfully created product"),
    @ApiResponse(responseCode = "400", description = "Invalid input")
})
@PostMapping("/products")
public ResponseEntity<Product> createProduct(@RequestBody Product product) {
    return productService.createProduct(product);
}

这些注解将帮助 Swagger 自动生成请求和响应的详细描述，并通过接口文档展示给前端开发人员或其他 API 使用者。

3. ✍️ 在 Spring Boot 中为 API 接口添加自定义注解，完善 API 文档信息

自定义注解

Swagger 3.0 提供了多种自定义注解，允许开发者为 API 接口添加更详细的描述，例如请求体（@RequestBody）、路径参数（@PathVariable）等：

@Operation(summary = "Search products by category", description = "Searches for products based on category")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Successfully retrieved products"),
    @ApiResponse(responseCode = "404", description = "Category not found")
})
@GetMapping("/search")
public List<Product> searchProducts(@RequestParam String category) {
    return productService.searchProductsByCategory(category);
}

参数化描述

您可以使用 @Parameter 注解为每个接口参数提供详细描述，以帮助 API 使用者理解参数的含义和用途。例如：

@Operation(summary = "Get product by ID", description = "Returns a product by its ID")
@Parameter(name = "id", description = "Product ID", required = true)
@GetMapping("/products/{id}")
public Product getProductById(@PathVariable Long id) {
    return productService.getProductById(id);
}

通过 @Parameter 注解，Swagger 3.0 会自动将该参数的信息展示在 API 文档中。

响应体的描述与示例数据

Swagger 允许开发者为接口的响应体提供详细的描述和示例数据，帮助使用者更好地理解响应的结构和内容。

@Operation(summary = "Create a new product", description = "Creates a new product")
@ApiResponse(responseCode = "200", description = "Successfully created product", content = @Content(
    schema = @Schema(implementation = Product.class),
    examples = @ExampleObject(value = "{\"name\":\"Product1\",\"price\":100.0}")
))
@PostMapping("/products")
public Product createProduct(@RequestBody Product product) {
    return productService.createProduct(product);
}

这种方式提供了详细的响应模型说明，并给出了 JSON 示例，帮助开发者理解返回数据的格式。

4. 🌐 使用 Swagger UI 可视化展示 API 文档并提供交互式接口测试功能

Swagger UI 集成

Swagger UI 是 Swagger 提供的一个非常强大的可视化工具，能够展示 API 文档并提供交互式接口测试功能。通过集成 Swagger UI，开发者可以在浏览器中查看所有的 API 接口，并且能够直接进行接口调用和测试。

只需在项目中添加 springdoc-openapi-ui 依赖，Swagger UI 就会自动集成到项目中，您可以通过访问 http://localhost:8080/swagger-ui.html 来查看 API 文档。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.6</version>
</dependency>

交互式接口测试

Swagger UI 提供了交互式测试功能，用户可以选择某个接口、输入请求参数并点击按钮发送请求，然后查看 API 返回的响应。Swagger UI 会自动生成请求的 URL，并展示响应体，帮助开发者调试和测试 API。

5. 📅 管理 API 文档版本，为每个版本提供独立文档展示

在微服务架构中，API 版本管理变得至关重要。随着系统的不断演进，新的 API 版本会逐渐替代旧版本，而旧版本的 API 仍需支持并为现有用户提供服务。为了确保 API 文档的正确性和兼容性，我们可以通过 Swagger 3.0 为不同版本的 API 提供独立的文档。

为不同版本的 API 提供独立文档

通过使用 @OpenAPIDefinition 注解，我们可以为不同版本的 API 提供独立的文档：

@OpenAPIDefinition(info = @Info(title = "Product API v1", version = "v1"))
@Configuration
public class ApiV1Config {
    // v1版本的配置
}

同样的，我们可以为 v2 版本的 API 定义一个单独的配置类：

@OpenAPIDefinition(info = @Info(title = "Product API v2", version = "v2"))
@Configuration
public class ApiV2Config {
    // v2版本的配置
}

通过路径访问不同版本的 API 文档

通过这种方式，Swagger UI 会为每个版本的 API 提供独立的文档，确保版本间的兼容性并方便开发者查看和使用。

6. 🧩 API 文档生成的最佳实践：清晰、易用与一致性

为了确保 API 文档能够高效、准确地服务于开发者和使用者，我们需要遵循一些最佳实践：

• 清晰的文档结构：确保 API 文档结构清晰，功能描述详细，响应格式规范。
• 统一的命名和描述：为所有的接口和参数使用统一的命名规则和描述风格。
• 自动化与实时同步：API 文档应与代码同步生成，避免手动编写文档时发生的错误。
• 提供示例数据：为每个请求和响应提供清晰的示例数据，帮助使用者更好地理解接口的使用方法。

7. 💡 总结与展望

通过集成 Swagger 3.0 与 Spring Boot，我们能够轻松生成高质量的 API 文档，并提供交互式测试功能。这不仅提升了开发效率，还能够帮助开发者和使用者更快速地理解和使用 API。同时，通过管理 API 版本和独立文档展示，我们可以更好地支持微服务架构中的版本兼容和向后兼容。

未来，随着 OpenAPI 规范的进一步发展和 Swagger 工具的持续更新，我们可以期待更多的功能和改进，例如增强的安全性描述、更细粒度的响应管理等，这将为开发者提供更强大、灵活的 API 文档生成和管理能力。

8. 🔍 延伸阅读与最佳实践

• OpenAPI 3.0 完整规范：深入理解 OpenAPI 3.0 的特性，提升 API 文档的可扩展性和标准化。
• API 文档的自动化与持续集成：学习如何将 API 文档生成纳入持续集成流程，确保文档实时与代码同步。
• Swagger 与 Redoc 对比：探索 Swagger 和 Redoc 在 API 文档展示和交互方面的差异，根据需求选择合适的工具。

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」专栏(全网一个名)，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

  最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

  同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G pdf电子书籍、简历模板、技术文章Markdown文档等海量资料。

✨️ Who am I?

我是bug菌(全网一个名)，CSDN | 掘金 | InfoQ | 51CTO | 华为云 | 阿里云 | 腾讯云 等社区博客专家，C站博客之星Top30，华为云多年度十佳博主/价值贡献奖，掘金多年度人气作者Top40，掘金等各大社区平台签约作者，51CTO年度博主Top12，掘金/InfoQ/51CTO等社区优质创作者；全网粉丝合计 30w+；更多精彩福利点击这里；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试真题、4000G PDF电子书籍、简历模板等海量资料，你想要的我都有，关键是你不来拿。

-End-