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

news2025/4/22 21:10:12

文章目录

- 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: true
    display-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 {
   

    @Bean
    public 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