章丘营销型网站设计公司开发公司财务管理制度
文章目录
- 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