在现代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文件中添加以下依赖：
org.springdoc springdoc-openapi-starter-webmvc-ui 2.7.0
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文档的维护和协作更加高效。
