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

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("[e-mail]").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