在 Spring Boot 中集成 OpenAPI 文档和 Swagger UI

在现代API开发中，OpenAPI规范和Swagger UI是不可或缺的工具，它们极大地简化了API文档的编写和测试流程。本文将引导您如何在Spring Boot 3项目中轻松集成OpenAPI文档和Swagger UI。

OpenAPI规范

OpenAPI规范（以前称为Swagger规范）是一种用于描述RESTful API的标准化语言。OpenAPI文件详细定义了API的各个方面，包括：

• 可用端点（例如/users）以及每个端点支持的操作（GET /users，POST /users）
• 参数：每个操作的输入和输出参数
• 认证方式
• 联系信息、许可证、使用条款等元数据

这些文档通常以YAML或JSON格式编写。

Swagger

Swagger是一套围绕OpenAPI规范构建的开源工具，它涵盖了API设计、构建、文档和使用等全生命周期。

Springdoc-OpenAPI

Springdoc-OpenAPI是一个Java库，它能够在Spring Boot应用中自动生成API文档。它支持生成JSON/YAML和HTML格式的API文档，极大地方便了开发者的工作。

快速上手

以下步骤将指导您如何在Spring Boot 3项目中集成Springdoc-OpenAPI：

前提条件

在开始之前，请确保您的开发环境满足以下要求：

• JDK 17或更高版本
• Spring Boot 3.x
• Maven或Gradle构建工具
• IDE（例如IntelliJ IDEA、Eclipse）

添加依赖

根据您的Spring Boot版本选择合适的Springdoc-OpenAPI版本（请参考Springdoc-OpenAPI的官方文档以获取最新的兼容性信息）。假设您使用的是Spring Boot 3.4.1，则对应的Springdoc-OpenAPI版本为2.7.0。

Maven:

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

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

Gradle:

在您的build.gradle文件中添加以下依赖：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'

验证集成

启动您的Spring Boot应用后，通过以下URL访问Swagger UI：

http://localhost:8080/swagger-ui/index.html

您应该能够看到生成的API文档。 要查看OpenAPI文档本身，请访问：

http://localhost:8080/v3/api-docs

自定义路径

您可以通过修改application.properties文件来自定义Swagger UI和OpenAPI文档的路径：

# 自定义OpenAPI文档路径
springdoc.api-docs.path=/api-docs

# 自定义Swagger UI路径
springdoc.swagger-ui.path=/swagger-ui.html

增强文档 (可选)

您可以使用各种注解来丰富您的API文档，例如：

• @Tag：按功能对API进行分组
• @Parameter：描述请求参数
• @RequestBody：描述请求体
• @ApiResponse：描述响应
• @Schema：描述数据模型

自定义OpenAPI配置 (可选)

您可以创建一个配置类来自定义OpenAPI文档的元数据，例如标题、描述、版本、联系信息等。

总结

通过简单的几步，您就可以在Spring Boot应用中集成OpenAPI文档和Swagger UI，从而显著提升API的可读性和可测试性。 这使得API文档的维护和协作更加高效。

以上就是在 Spring Boot 中集成 OpenAPI 文档和 Swagger UI的详细内容，更多请关注图灵教育其它相关文章！