一. 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) {}
}
http://localhost:8080/swagger-ui/index.html#/
