拥抱Swagger 2：打造优雅的Spring Boot在线接口文档系统（准备篇）

2023-11-10 11:21:24

迈向优雅文档的准备之旅

在软件开发领域，API 文档是沟通开发人员和使用者的重要桥梁。一份精心编写的文档可以显著提高 API 的可理解性、可用性和可维护性。Swagger 2 是一个广受欢迎的工具，可以帮助我们轻松构建交互式 API 文档。

安装 Swagger 2

安装 Swagger 2 有多种方式。对于 Spring Boot 应用程序，我们推荐使用官方提供的 springdoc-openapi 依赖项。它可以与 Spring Boot 轻松集成，并且提供了丰富的功能。

在您的 pom.xml 文件中添加以下依赖项：

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

在 Spring Boot 应用程序中，我们可以通过在 application.properties 或 application.yml 文件中添加以下配置来启用 Swagger 2：

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

这将为 Swagger 2 UI 指定一个访问路径，通常是 /swagger-ui.html。

在使用 Swagger 2 之前，我们需要了解一些基本概念。

OpenAPI 规范： OpenAPI 规范是用于 REST API 的一种标准化格式。Swagger 2 使用 OpenAPI 规范来 API 的结构和行为。
Swagger 文档： Swagger 文档是根据 OpenAPI 规范生成的，它包含了 API 的详细描述，包括端点、参数、响应等信息。
Swagger UI： Swagger UI 是一个交互式 Web 界面，可以用来查看和测试 API。它提供了美观、易用的界面，可以帮助开发者快速了解和使用 API。