【亲测免费】 Springdoc-OpenAPI 安装和配置指南

1. 项目基础介绍和主要的编程语言

项目基础介绍

Springdoc-OpenAPI 是一个用于自动化生成 API 文档的 Java 库，适用于 Spring Boot 项目。它通过在运行时检查应用程序来推断 API 语义，基于 Spring 配置、类结构和各种注解生成 API 文档。生成的文档可以以 JSON/YAML 和 HTML 格式呈现，并且可以通过 Swagger-API 注解进行补充。

主要的编程语言

该项目主要使用 Java 编程语言，同时也支持 Kotlin。

2. 项目使用的关键技术和框架

关键技术和框架

• Spring Boot: 用于简化 Spring 应用程序的初始搭建和开发。
• OpenAPI 3: 用于定义 API 的标准规范。
• Swagger UI: 用于可视化 API 文档的工具。
• JSR-303: 用于 Bean Validation，支持注解如 @NotNull, @Min, @Max, 和 @Size。
• OAuth 2: 用于 API 的安全认证。
• GraalVM: 用于生成原生镜像。

3. 项目安装和配置的准备工作和详细的安装步骤

准备工作

1. Java 环境: 确保你已经安装了 Java 17 或更高版本。
2. Maven 或 Gradle: 确保你已经安装了 Maven 或 Gradle 构建工具。
3. Spring Boot 项目: 确保你已经有一个 Spring Boot 项目。

安装步骤

步骤 1: 添加依赖

在你的 Spring Boot 项目的 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version> <!-- 请根据最新版本更新 -->
</dependency>

步骤 2: 配置 Spring Boot 应用程序

在你的 Spring Boot 应用程序配置文件（如 application.properties 或 application.yml）中添加以下配置：

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

步骤 3: 启动 Spring Boot 应用程序

启动你的 Spring Boot 应用程序，访问以下 URL 以查看生成的 API 文档：

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

步骤 4: 验证安装

确保你可以在浏览器中访问 Swagger UI 页面，并且 API 文档正确显示。

可选配置

自定义 API 文档路径

如果你希望自定义 API 文档的路径，可以在配置文件中添加以下内容：

# /api-docs 端点自定义路径
springdoc.api-docs.path=/api-docs

禁用 API 文档端点

如果你希望禁用 API 文档端点，可以在配置文件中添加以下内容：

# 禁用 api-docs
springdoc.api-docs.enabled=false

通过以上步骤，你已经成功安装并配置了 Springdoc-OpenAPI，可以在你的 Spring Boot 项目中自动生成和查看 API 文档。