# Swagger

Swagger 是一間名為SmartBear Software 的公司，開發出的REST API 的工具，可以幫助設計、構建、記錄和使用REST API，後來貢獻給OpenAPI Initiative，並公開讓所有人都能夠使用。

<iframe src="https://excalidraw.com/#json=aAHIg1Ze3vilk-IH-YE1i,NxWQy1Fzdzsv3yhMADQyXw" width="100%" height="600px"></iframe>

## Swagger 簡史 與 OPENAPI

Swagger 最早由非營利組織 Wordnik 開發
2011 年 8 月 Swagger 發布 1.0 版本
2014 年 9 月 Swagger 發布 2.0 版本
2015 年 3 月 SmartBear Software 收購 Wordnik 手上的 Swagger API 規範
2015 年 11 月 SmartBear Software 將 Swagger API 規範捐贈給 Linux 基金會
2016 年 Swagger 規範更名為 OpenAPI 規範 (Open API Initiative, OAS)
2017 年 7 月 OpenAPI 發布 3.0.0 版本
2021 年 2 月 OpenAPI 發布 3.1.0 版本

因為先發布 Swagger 2.0，才捐贈給 Linux 基金會，所以雖然 OpenAPI 規範 2.0 等於 Swagger 2.0，但網路上的文章基本上都是寫 Swagger 2.0 而不是 OpenAPI 2.0
OpenAPI 規範是什麼？
應用程式介面(Application Programming Interface, API)，是一種讓應用程式與第三方程式或網站進行交互的方式。
而 API 資訊文件該怎麼撰寫呢？這就是 OpenAPI 規範的用途了。依照這個規則，大家就知道 get, post 或是查詢參數要怎麼寫在文件上面
Swagger 工具是什麼？
SmartBear Software 公司捐出去的只有「規範」，以粗略的比喻來說就像是 Json 的大括號後面要接小括號，陣列要怎麼呈現出來這樣。
SmartBear Software 公司仍然保有他們開發的各式各樣的「工具」，例如能夠及時預覽的線上編輯器等等。

他們有的各類工具(服務)：
Swagger UI ： 將 OpenAPI 格式的文件以 HTML 的形式顯示，能夠在網頁中直接測試呼叫 API 並回應測試資訊。
Swagger Editor : YAML 格式的線上編輯工具，能夠及時瀏覽文件，以 Swagger UI 的方式呈現。
Swagger Codegen ： 從 OpenAPI 文件自動產生成各種語言的 API 實作。
Swagger Parser ： 從 OpenAPI 文件建立 Java 實作。
Swagger Core ： 用於建立和使用 OpenAPI 定義的 Java 相關類別庫
Swagger Inspector ： 在雲端測試 API 的工具。
SwaggerHub ： Swagger Editor 的進階版，再加上文件儲存、發布、分享等功能(免費版本只能設定為公開)
...待補充

不過，我們現在常說的 Swagger，其實應該是在說 Swagger 工具，而不是「單純的 Swagger 規範」。

資料來源: https://www.ruyut.com/2022/05/openapi-swagger.html

## 使用 Swagger 來自動產生可互動的 API 文件

@StanShih

## Using the Editor on the Web
https://editor.swagger.io/?_ga=2.143193585.535853691.1701315169-19954188.1701315168

多平台都可使用，npm、java、.Net、docker