11.Spring Boot 3.1.5 中使用 SpringDoc OpenAPI（替代 Swagger）生成 API 文档

原创

已于 2025-04-30 17:51:10 修改 · 1k 阅读

13 ·

CC 4.0 BY-SA版权

我是Alsn,那半个橘子是海上遇到大雨时侯的明亮橘色灯塔!

文章标签：

#spring boot #java #后端

于 2025-04-30 16:41:23 首次发布

Spring Boot 3.1.5 中使用 SpringDoc OpenAPI（替代 Swagger）生成 API 文档

1. 项目结构

假设项目名为 springboot-openapi-demo，以下是项目的基本结构：

springboot-openapi-demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── demo/
│   │   │               ├── DemoApplication.java        # 主启动类
│   │   │               ├── config/                     # 配置类目录
│   │   │               │   └── OpenApiConfig.java      # OpenAPI 配置类
│   │   │               ├── controller/                 # 控制器目录
│   │   │               │   └── UserController.java     # 示例控制器
│   │   │               └── model/                      # 模型类目录
│   │   │                   └── User.java               # 用户模型类
│   │   └── resources/
│   │       └── application.properties                 # 配置文件
└── pom.xml                                             # Maven 依赖配置

2. 创建 `pom.xml` 并添加依赖

在 pom.xml 中添加 Spring Boot 和 SpringDoc OpenAPI 的依赖：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.5</version>
        <relativePath/> <!-- 查找父 POM 的位置 -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>springboot-openapi-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-openapi-demo</name>
    <description>Spring Boot 3.1.5 + SpringDoc OpenAPI 示例</description>

    <properties>
        <java.version>17</java.version> <!-- 指定 JDK 17 -->
        <springdoc-openapi.version>2.3.0