当前位置：首页 > news >正文

SpringBoot 3 与 SpringDoc 打造完美接口文档

news 来源：原创 2025/4/23 19:38:39

文章目录

- 1. SpringDoc 简介
- - 1.1 SpringDoc 优势
- 2. 环境准备
- - 2.1 Maven 依赖
  - 2.2 基础配置
- 3. 创建基本文档配置类
- 4. 控制器 API 文档注解
- - 4.1 基本控制器示例
  - 4.2 模型类示例
- 5. 高级功能
- - 5.1 API分组
  - 5.2 安全配置
  - 5.3 隐藏特定端点
- 6. 参数描述
- - 6.1 路径参数
  - 6.2 查询参数
  - 6.3 请求体
- 7. 响应文档化
- - 7.1 基本响应
  - 7.2 详细响应内容
  - 7.3 自定义响应模型
- 8. 访问文档
- 9. 常见问题及最佳实践
- - 9.1 常见问题
  - 9.2 最佳实践
- 10. 完整示例

1. SpringDoc 简介

SpringDoc 是一个开源工具，它集成了 OpenAPI 3 和 Swagger UI，可以自动为基于 Spring Boot 开发的 REST API 生成 API 文档。SpringDoc 替代了过去的 SpringFox，并提供了与 SpringBoot 3 更好的兼容性。

1.1 SpringDoc 优势

支持 OpenAPI 3 规范
与 SpringBoot 3 完美集成
自动扫描并生成 API 文档
支持丰富的注解来定制 API 文档
提供 Swagger UI 进行文档可视化
支持分组、安全配置等高级特性

2. 环境准备

2.1 Maven 依赖

在 SpringBoot 3 项目中添加 SpringDoc 依赖：

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

对于 WebFlux 项目，使用：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webflux-ui</artifactId><version>2.3.0</version>
</dependency>

2.2 基础配置

在 application.yml 中添加基础配置：

springdoc:api-docs:enabled: true                  # 启用/禁用API文档的访问path: /v3/api-docs            # 设置API文档的访问路径swagger-ui:path: /swagger-ui.html        # 设置Swagger UI的访问路径disable-swagger-default-url: truedisplay-request-duration: true # 显示请求持续时间packages-to-scan: com.example.controller # 指定要扫描的包paths-to-match: /api/**, /public/** # 指定要匹配的路径

3. 创建基本文档配置类

创建一个配置类来自定义 API 文档：

package com.example.config;import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title("我的API文档").description("Spring Boot 3 应用接口文档").version("v1.0.0").contact(new Contact().name("开发者").email("developer@example.com").url("https://www.example.com")).license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0"))).externalDocs(new ExternalDocumentation().description("更多文档").url("https://springdoc.org"));}
}

4. 控制器 API 文档注解

4.1 基本控制器示例

package com.example.controller;import com.example.model.User;
import com.example.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas