一. swagger3介绍

Swagger 3 是基于 OpenAPI 规范 3.0 的 API 文档工具，用于设计、构建和消费 RESTful API。它通过标准化描述 API 的接口、参数、响应等元数据，实现以下核心功能：

自动生成交互式文档
API 测试与调试
代码生成（客户端/服务端）
多语言支持

二. Swagger3 vs Swagger 2.0

以下表格总结了Swagger 2.0和OpenAPI 3.0（Swagger 3.0）的主要差异：

特性	Swagger 2.0	OpenAPI 3.0
规范名称	Swagger	OpenAPI
文件扩展名	`.json` 或 `.yaml`	`.json` 或 `.yaml`
API 描述结构	基于资源路径和操作	支持更灵活的组件复用
服务器定义	仅支持单一服务器 URL	支持多服务器配置，包括环境变量
请求参数类型	仅支持 `query`、`header`、`path`、`formData`、`body`	新增 `cookie` 参数类型，更细粒度的参数控制
请求体支持	仅支持单一请求体	支持多请求体类型（如 `multipart`）
响应定义	仅支持全局响应模型	支持操作级响应模型，更灵活
安全方案	支持 `basic`、`apiKey`、`oauth2`	新增 `openIdConnect`，支持 JWT
外部文档链接	不支持	支持 `externalDocs` 引用外部文档
回调功能	不支持	支持 WebHook 和异步操作的回调定义
兼容性	广泛兼容旧工具	需要较新的工具链支持

OpenAPI 3.0 在以下方面进行了优化：

组件复用：通过 components 模块复用模型、参数、响应等，减少冗余代码。
多服务器配置：允许定义多个服务器环境（如开发、测试、生产），便于动态切换。
更丰富的参数类型：新增 cookie 参数支持，适配现代 API 需求。
异步支持：通过 callbacks 定义事件驱动的 API 行为。

三. 添加依赖

		// Swagger3<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>// Swagger2<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!-- Swagger UI 依赖（可选，用于可视化界面） --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

四. 配置Swagger3

@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info()  // 创建文档信息对象.title("API 文档")   // 设置文档标题.version("1.0.0")    // 设置API版本号.description("项目接口文档")  // 添加详细描述.contact(new Contact()  // 设置联系人信息.name("还没秃顶的兔子")     // 联系人姓名
//                                .url("https://example.com")  // 联系人网址.email("email@example.com"))  // 联系人邮箱.license(new License()  // 设置许可证信息.name("Apache 2.0")  // 许可证名称.url("https://springdoc.org")));  // 许可证详情URL}}

五. 接口定义

@RestController
@RequestMapping("/api")
@Tag(name = "学校管理", description = "学校管理接口")
public class SchoolsController {@Operation(summary = "添加学校", description = "创建新学校并初始化管理员账号")@PostMapping("/addSchools")private Result<Schools> addSchools(@RequestParam String name, String address) {}
}