今天棧長(zhǎng)給大家推薦一款接口 API 設(shè)計(jì)神器，傳說中的，牛逼哄洪的 Swagger，它到底是什么？今天為大家揭開謎底！

Swagger是什么？

官網(wǎng)：https://swagger.io/

Swagger 如官網(wǎng)所示，它是***的 API 構(gòu)建工具。

它是一個(gè)圍繞 OpenAPI 規(guī)范構(gòu)建的開源工具，它可以幫助我們?cè)O(shè)計(jì)、構(gòu)建、記錄和使用 REST API 接口。

Swagger 包含的主要套件：

• Swagger Editor - 基于瀏覽器的編輯器，用來編寫 OpenAPI 規(guī)范。
• Swagger UI - 基于 OpenAPI 規(guī)范動(dòng)態(tài)生成 API 規(guī)范文檔。
• Swagger Codegen - 個(gè)模板驅(qū)動(dòng)引擎，用來生成客戶端代碼。

圖片來源見博客水印。

OpenAPI是什么？

上面有說到 Swagger 是一個(gè)圍繞 OpenAPI 規(guī)范構(gòu)建的開源工具，那么 OpenAPI 是什么呢？

OpenAPI 規(guī)范，以前叫 Swagger 規(guī)范。它是一個(gè)為 REST APIs的接口定義的規(guī)范。OpenAPI 可以定義的 API 實(shí)體內(nèi)容包括以下幾個(gè)部分。

• 請(qǐng)求地址（如：/user）
• 請(qǐng)求類型（如：GET、POST 等）
• 請(qǐng)求參數(shù)
• 響應(yīng)參數(shù)
• 驗(yàn)證方式
• 文檔信息：如聯(lián)系人、許可證、服務(wù)條件等

這個(gè) OpenAPI 規(guī)范可以用 YAML 或者 JSON 來編寫，這種格式非常易于學(xué)習(xí)，可讀性對(duì)開發(fā)人員非常友好。

完整的 OpenAPI 規(guī)范可以去官網(wǎng)看一下。

https://github.com/OAI/OpenAPI-Specification

編寫文檔地址：

http://editor.swagger.io/

為什么需要Swagger？

現(xiàn)在的互聯(lián)網(wǎng)架構(gòu)都是前后端分離的模式，還有現(xiàn)在是移動(dòng)互聯(lián)網(wǎng)時(shí)代了，APP 需要與后端服務(wù)器通信也需要維護(hù)一套接口，API文檔自然就成了前后端開發(fā)人員聯(lián)系的紐帶。

編寫 API 文檔的方式也各有不同，有用 WORD 編寫的，有用 confluence 等編寫的，但這些方式都不能動(dòng)態(tài)更新，每次接口變更都需要手動(dòng)維護(hù)文檔，甚是麻煩。有了 Swagger，可以先做完接口，通過 Swagger 來動(dòng)態(tài)生成和更新 API 文檔。

后面的文章會(huì)繼續(xù)介紹如何使用 Swagger 注解來自動(dòng)生成 API 文檔，及如何集成 Spring Boot 來應(yīng)用實(shí)戰(zhàn)。