Swagger 是一個用于描述、生成、文檔化和測試 RESTful API 的開源工具集。它可以自動生成 API 文檔，幫助開發者理解和使用 API。Swagger 由 Swagger.io 提供，并已經發展成了一套廣泛應用于 API 設計和文檔的標準。

Swagger 項目的歷史可以追溯到 2010 年，它最初由 Tony Tam 創建。當時，API 開發者通常需要花費大量時間手動編寫和維護文檔，并且手動維護文檔容易與實際 API 的實現不一致，導致文檔和實際接口的差異。Swagger 的設計目標就是通過自動生成文檔，減少這些手動工作，提高開發效率。

發展歷程

1. 2011年：

   • Swagger 在?GitHub?上開源發布，迅速吸引了開發者的關注。它提供了一個簡單的注解系統，開發者通過在代碼中添加注解即可自動生成 API 文檔。Swagger 可以幫助開發者和團隊更好地理解和使用 API。

2. 2015年：

   • Swagger 被納入?OpenAPI Initiative (OAI)，一個由多個技術公司和開源社區組成的組織，旨在制定開放的 API 規范。OpenAPI 規范（OAS，OpenAPI Specification）取代了原有的 Swagger 規范，成為更加標準化的 API 描述格式。
   • Swagger 工具集的名字也被保持了下來，仍然用于描述和生成 API 文檔，而 OpenAPI 則成為技術規范。

3. 2016年：

   • Swagger 發布了?Swagger 2.0，并繼續進行更新與完善。Swagger 2.0 是 Swagger 生態系統的基礎，至今仍被廣泛使用。

4. 2017年以后：

   • OpenAPI 3.0 規范發布，它包含了對 Swagger 2.0 的改進和擴展，提供了更強大的功能。Swagger 的工具鏈也開始支持 OpenAPI 3.0 規范，并向兼容性過渡。

Swagger 的主要組件

Swagger 的工具集包括多個組成部分，使得開發者可以更好地設計和管理 API：

1. Swagger Editor：

   • 一個基于 Web 的編輯器，可以幫助開發者編寫和編輯 OpenAPI 規范文件（通常為?swagger.yaml?或?swagger.json?文件）。它支持實時預覽和驗證 API 規范。

2. Swagger UI：

   • Swagger UI 是一個基于瀏覽器的界面，提供交互式文檔界面，允許開發者和用戶查看 API 文檔，并直接在文檔界面上測試 API 的各個端點。

3. Swagger Codegen：

   • Swagger Codegen 允許開發者從 OpenAPI 規范中自動生成客戶端 SDK、服務器端代碼和 API 文檔。這些代碼生成器支持多種編程語言和框架。

4. Swagger Hub：

   • Swagger Hub 是一個商業化平臺，用于協作設計、構建和管理 API 文檔。它提供了基于云的 API 管理、版本控制和協作功能，適用于企業級應用。

Swagger 的優點

• 自動化文檔生成：通過注解，Swagger 可以自動生成 API 的文檔，避免手動編寫文檔，減少出錯概率。
• 易于使用：開發者可以通過簡單的注解和配置文件來定義 API，Swagger UI 提供了交互式的界面，方便開發者和用戶查看和測試 API。
• 開源和廣泛支持：Swagger 是開源的，得到了廣泛的社區支持，并且能夠與許多開發框架（如 Spring、Node.js、Java、Python 等）兼容。

Swagger 的使用

1.?@Api

• 作用：用于標記一個類是一個 Swagger 資源（通常是一個 Controller 類）。
• 常見用法：

• @Api(tags = "用戶管理", description = "管理用戶的 API")
  public class UserController {// 控制器代碼
  }
  

2.?@ApiOperation

• 作用：描述單個 API 操作（通常是一個方法），提供接口的詳細信息，如功能說明、HTTP 方法、響應類型等。
• 常見用法：

  @ApiOperation(value = "獲取用戶列表", notes = "獲取所有用戶的列表", response = User.class)
  @GetMapping("/users")
  public List<User> getUsers() {// 代碼
  }
  

3.?@ApiParam

• 作用：用于描述方法參數的詳細信息（例如：是否必需、默認值等）。
• 常見用法：

  @ApiOperation("獲取指定用戶")
  @GetMapping("/user/{id}")
  public User getUser(@ApiParam(value = "用戶ID", required = true) @PathVariable Long id) {// 代碼
  }
  

4.?@ApiResponse

• 作用：描述 API 操作的響應信息，例如狀態碼和響應類型。
• 常見用法：

  @ApiOperation(value = "刪除用戶", notes = "刪除指定用戶")
  @ApiResponses({@ApiResponse(code = 200, message = "刪除成功"),@ApiResponse(code = 404, message = "用戶未找到")
  })
  @DeleteMapping("/user/{id}")
  public ResponseEntity<Void> deleteUser(@PathVariable Long id) {// 代碼
  }
  

5.?@ApiModel

• 作用：用于定義 API 中的復雜對象模型（即請求體或響應體），例如對象參數或返回的復雜數據類型
• 常見用法：

• @ApiModel(description = "用戶對象")
  public class User {@ApiModelProperty(value = "用戶ID", required = true)private Long id;@ApiModelProperty(value = "用戶姓名", example = "張三")private String name;
  }
  

6.?@ApiModelProperty

• 作用：用于為模型屬性提供詳細描述，包括字段說明、是否必填、默認值等。
• 常見用法：

• public class User {@ApiModelProperty(value = "用戶ID", required = true)private Long id;@ApiModelProperty(value = "用戶姓名", example = "張三")private String name;
  }
  

7.?@PathParam,?@QueryParam,?@HeaderParam,?@FormParam

• 作用：用于綁定 HTTP 請求的路徑、查詢參數、請求頭和表單參數。它們分別對應不同類型的參數提取。
• 常見用法：

• @GetMapping("/user")
  public User getUser(@QueryParam("id") Long id) {// 代碼
  }
  

8.?@RequestBody

• 作用：用于標注方法參數接收請求體的數據，通常用來處理 JSON 或 XML 格式的請求。
• 常見用法：

• @PostMapping("/user")
  public User createUser(@RequestBody User user) {// 代碼
  }
  

9.?@RequestMapping,?@GetMapping,?@PostMapping,?@PutMapping,?@DeleteMapping

• 作用：用于定義 API 的 HTTP 請求類型和 URL 路徑。
• 常見用法：

• @GetMapping("/user/{id}")
  public User getUser(@PathVariable Long id) {// 代碼
  }

10.?@Consumes,?@Produces

• 作用：用于標注接口支持的內容類型，通常用于描述請求和響應的格式（如 JSON、XML 等）。
• 常見用法：

• @Consumes("application/json")
  @Produces("application/json")
  @PostMapping("/user")
  public ResponseEntity<User> createUser(@RequestBody User user) {// 代碼
  }
  

11.?@SwaggerDefinition

• 作用：用來描述 Swagger 配置的元數據，如 API 的標題、版本、描述等。
• 常見用法：

• @SwaggerDefinition(info = @Info(title = "用戶管理 API", version = "1.0", description = "提供用戶管理相關的操作")
  )
  public class UserController {// 控制器代碼
  }
  

12.?@ResponseStatus

• 作用：用于指定 HTTP 響應的狀態碼，通常與?@ExceptionHandler?配合使用，定義異常的響應狀態。
• 常見用法：

• @ResponseStatus(value = HttpStatus.NOT_FOUND, reason = "用戶未找到")
  public class UserNotFoundException extends RuntimeException {// 代碼
  }
  

OpenAPI 和 Swagger 的關系

隨著 OpenAPI Initiative 的出現，Swagger 成為了 OpenAPI 規范的工具之一。雖然 OpenAPI 規范變成了行業標準，但 Swagger 依然是最常用的工具集之一，并且支持 OpenAPI 3.0 規范。可以將 Swagger 理解為 OpenAPI 規范的工具實現，它包括了多種工具和框架來幫助開發者設計、文檔化和測試 API。

總結

Swagger 從最初的一個 API 文檔工具，逐漸發展成為一個完整的工具鏈，幫助開發者更高效地設計和管理 API。隨著 OpenAPI 規范的推行，Swagger 成為這一規范的核心工具，繼續服務于全球的開發者社區。

---

天不老，情難絕，信似雙絲網，中有千千結