swagger的基本使用
由于工作需要，在这里在复习一下swagger这个技术栈
对swagger有个完整性的认识：
首先，我们先确定一下这个技术栈是干什么的
1.管理项目的所有接口
2.让接口信息可视化。
如果项目无法在本地跑起来，又要对接口有一定的基础性认识。
就用这个是个不错的选择。
由于时间原因，无法做一个系统，完整的介绍，先做一个demo性的总结。
关于swagger我们要掌握什么信息
1.springboot如何引入swagger项目
2.引入swgger需要配置什么内容，配置这些内容是为了管理什么东西
3.引入swagger以后，如何在控制台上管理，使用接口
4.单个接口需要暴露哪些信息给swgger控制台。
一、Swagger 是干什么的？（再强化认知）
不是测试工具，而是「契约先行 + 文档自动生成 + 可交互调试」三位一体的 API 管理方案
自动生成符合 OpenAPI 规范（3.0+）的 JSON/YAML 接口描述
提供 Web UI（Swagger UI）可视化所有接口（路径、参数、请求体、响应、状态码等）
支持在线调试：直接在页面填参 → 发请求 → 看响应（等价于 Postman 简化版）
支持导出 OpenAPI 文档，供前端/测试/第三方集成使用（如生成 TS 客户端）
核心价值：
开发阶段：减少前后端沟通成本，“文档即代码”
维护阶段：接口变更自动同步文档，避免文档滞后
协作阶段：非开发人员（测试、产品）可直观理解 API
二、4 个核心问题实战解答（Spring Boot 3 + SpringDoc）
Spring Boot 如何引入 Swagger？（依赖配置）
使用 springdoc-openapi-starter-webmvc-ui（Spring Boot 3 推荐，替代 Springfox）
xml
123456
Spring Boot 2.x 可用 springdoc-openapi-ui（旧版 starter）
若用 WebFlux → 换 springdoc-openapi-starter-webflux-ui
无需额外配置类即可运行（默认 /v3/api-docs + /swagger-ui.html）
需要配置什么？管理哪些东西？
通过 application.yml 配置全局信息（非必须，但强烈建议）：
yaml
123456789
application.yml
springdoc:
api-docs:
enabled: true
swagger-ui:
path: /swagger-ui.html
operations-sorter: method
tags-sorter: alpha
try-it-out-enabled: true
这些配置管理什么？
info.：API 元信息（标题/描述/版本/作者），展示在 UI 顶部
swagger-ui.：UI 行为（是否可调试、排序方式、路径等）
group-configs：接口分组（按路径/包/注解分离 API，避免混杂）
api-docs.enabled：文档生成开关（生产环境建议关闭）
进阶：可用 @OpenAPIDefinition 注解替代 info 配置（Java 配置更灵活）
引入后，如何在控制台管理/使用接口？
启动项目后访问：
http://localhost:8080/swagger-ui.html
UI 界面核心功能：
顶部栏：API 标题/描述/搜索框/Authorize（鉴权配置）
左侧分组：按 Controller 或 @Tag 注解分组
接口卡片：展开后包含
• 请求方法（GET/POST…）
• 路径 /api/user/{id}
• 参数（Query/Header/Path/Body）
• 示例请求体（JSON Schema）
• 响应示例（200/400/500）
Try it out：点击 → 填参数 → Execute → 查看实际请求/响应
重要操作：
Authorize：若接口需 Token，点右上角 “Authorize” 输入 Bearer Token
Models：底部查看全局 DTO 的 JSON Schema 结构
Download：右上角可导出 OpenAPI JSON/YAML
单个接口需要暴露哪些信息给 Swagger？
通过注解补充接口语义（核心 5 个）：
java
123456789101112
@RestController
@RequestMapping(“/api/user”)
@Tag(name = “用户管理”, description = “用户 CRUD 相关接口”)
public class UserController {
@Operation( summary = "根据ID查询用户", description = "返回用户详细信息，ID 不存在时返回 404", responses = { @ApiResponse(responseCode = "200", description = "查询成功")注解功能速查：
@Tag：Controller/方法分组，属性 name, description
@Operation：描述单个接口，属性 summary, description, responses
@Parameter：描述参数（Path/Query/Header），属性 description, required, example
@RequestBody（springdoc）：描述请求体，属性 description, required, content
@ApiResponse：描述响应，属性 responseCode, description, content
最佳实践：
DTO 类字段用 @Schema(description = “用户名”, example = “张三”) 补充说明
枚举值自动识别 → 无需额外配置
校验注解（如 @NotBlank）会自动体现在 required 和 Schema 中
补充：生产环境建议
生产环境暴露文档？
禁止！用 Profile 控制：@Profile(“!prod”) 或 springdoc.api-docs.enabled=false
接口需要登录？
在 Swagger UI 的 Authorize 配置 Bearer Token（需后端支持）
自定义 UI 页面？
不推荐。如必须，可替换 META-INF/resources/webjars/swagger-ui/ 下静态资源
速查命令（本地启动后）
http://localhost:8080/swagger-ui.html —— 可视化 UI
http://localhost:8080/v3/api-docs —— 原始 OpenAPI JSON
http://localhost:8080/v3/api-docs.yaml —— OpenAPI YAML（适合存档