# Swagger/OpenAPI 介紹 ![](https://hackmd.io/_uploads/B1QcbedP2.png =300x) ## Swagger/OpenAPI 是什麼? ### Swagger ? Swagger 是一組用於編寫基於 REST 的 API 的開源 open source 工具。它通過接口、指定標準和提供編寫美觀、安全、高性能和可擴展的 API 所需的工具來簡化編寫 API 的過程。 ### OpenAPI ? Open API 文件包含 API 的完整規範。它可以幫助開發人員完整地描述他們的 API，例如列出每個端點上可用的端點和操作。進入方法的參數和方法的響應。身份驗證方式、許可等元數據、使用條款等。 OpenAPI 是全球採用的標準，任何人在 RESTful API 開發和編寫過程中都必須遵循。通過嚴格遵守 OpenAPI，開發人員確保他們正在創建世界上任何人都可以使用並期待統一結果的 RESTful API。它旨在實現 RESTful API 的無縫性，同時對 API 安全、錯誤處理、API 版本控制和其他關鍵內容進行盡職調查。 ### 那 Swagger 和 OpenAPI 的關係? OpenAPI 是規範，Swagger 是規範的實現。 最初，OpenAPI 被稱為 Swagger 規範。Swagger 提出了構建 API 的最佳實踐，然後這些最佳實踐成為了 OpenAPI 規範。 ![](https://hackmd.io/_uploads/rkSLfguPh.png) ## 為什麼要用 Swagger/OpenAPI ? ### API 文件與 Swagger :::warning #### 對於 API 是什麼不知道的可以看看以下影片來了解 - [行雲者研發基地 1111學期 第十周組聚教學影片 - API介紹](https://www.youtube.com/watch?v=PS1VD_cB91k&list=PLxDGb_dFP7ePp6BROIeEs7TgJek15OEuA&index=8) - [Termsoup - 什麼是 API？](https://www.youtube.com/watch?v=zvKadd9Cflc) API 是為了讓兩個服務之間可以溝通、互動所產生的接口。而所有的溝通要有效，都一定要先有共識，隨著溝通的人數越來越多，或是內容的理解要越來越細，就會用文件或契約的方式來達成共識，也就是要寫 ==**API 規格文件**==。 ::: 在一般的工作情境中，開發人員要寫 API 文件時，很容易就會去使用 Word、Excel，抑或會使用 HackMD 作為文件的提供，但是這類的文件，會有維護與修改的問題，比如改了參數但是忘記更新文件，或是手誤打錯，都會是 ==溝通成本==。 ### 而這就是 Swagger 的用武之地 Swagger 能夠透過該程式語言透過工具自動生成 API 文件，並能 ==線上進行測試==，正好可以解決上述問題，讓我們在溝通、開發和測試更快的達成共識與解決問題。 ### 資安與測試用途 #### 資安 - [OWASP官網](https://owasp.org/www-project-api-security/) Swagger 所產生的 yml 格式檔屬於 OpenAPI 規範，可以匯入 **OWASP** 進行 API 安全檢查，可以自行看~ ![](https://hackmd.io/_uploads/r15O9Wdvn.png =200x) #### 測試 [Postman官網](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/) Postman 可以將 API 規範文件(也就是我們的 OpenAPI 規範)匯入進去，就可以在自己電腦使用 [Postman 使用文件](https://israynotarray.com/other/20211207/427026/) ![](https://hackmd.io/_uploads/Hk72cb_D2.png =300x) ### 總結上述 - Swagger 優點 - 以 REST 風格 - 以程式碼撰寫或註解解決 - 程式碼異動、文檔卻忘記改動的問題 - 因為修改文件而需要花的時間 - 測試資料、欄位的問題 - 以網頁或產生的 yml格式檔解決 - 溝通時間成本，讓不同團隊開發知道如何使用 API 接口 - 傳達所有回應的狀態與資訊 - 可線上測試 API 回應結果 - 格式檔下載後可匯入至 OWASP、Postman 進行資安檢查與測試 --- #### 文件參考 - [什麼是SWAGGER？為什麼你的案子需要它？](https://www.keywordseo.com.tw/blog/what-is-swagger-and-why-do-you-need-it-for-your-project/) - [菜雞新訓記 (4): 使用 Swagger 來自動產生可互動的 API 文件吧](https://igouist.github.io/post/2021/05/newbie-4-swagger/) - [使用Swagger自動產生API文件](https://lib11.medium.com/%E4%BD%BF%E7%94%A8swagger%E8%87%AA%E5%8B%95%E7%94%A2%E7%94%9Fapi%E6%96%87%E4%BB%B6-a8f5c65d267c) - [[Day09]使用Swagger自動建立清晰明瞭的REST API文件 - 我與 ASP.NET Core 的 30天](https://ithelp.ithome.com.tw/articles/10242295) - [Documenting Your Existing APIs: API Documentation Made Easy with OpenAPI & Swagger](https://swagger.io/resources/articles/documenting-apis-with-swagger/) - [What is a Swagger Editor ?](https://www.wallarm.com/what/what-is-a-swagger-editor)