初次接觸Swagger是在2017年5月，當時公司正好要對整套系統架構進行重新設計，有同事推薦用這個技術框架來規範後臺接口的API文檔。當時因為架構重構，涉及改造的技術點太多，一時也就沒太多精力，把Swagger暫時放下了。對於API文檔我們就自己定義了一個模板，統一要求開發人員把文檔寫在tower上了。

現在回頭來看，存在這麽幾個問題：

1. 文檔編寫及修改的及時性不夠，由於API在開發及測試過程中經常會有調整，相應的文檔不能及時得到修改。

2. 文檔的規範性需要人為的檢查來約束，增大了項目管理的工作量

3. 前端和測試人員對文檔的理解有一個過程，有時需要頻繁和後臺開發人員進行交流，產生了一定的交流成本。

由於現在的互聯網項目都是前後端合作的形式，前端和後端的唯一聯系，變成了API接口；API文檔變成了前後端開發人員聯系的紐帶，變得越來越重要，在這樣的情況下，我又把註意力再次投向了Swagger。經過幾天研究，大致有了比較清晰的認識，準備寫幾篇博客對這個技術進行一下說明。

Swagger這個單詞做形容詞是 “炫耀的；時髦的” 這樣一個意思。官網地址： https://swagger.io ，官網對其項目的定義是：

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.　　　　　　　　　　　　　　　　

中文意思是：Swagger是一個大型的API開發者的工具框架，該框架提出了一個編寫OpenAPI的規範（命名為OAS），並且Swagger可以跨整個API生命周期進行開發，從設計和文檔到測試和部署。

Swagger這個框架的原理：框架提出了一個文檔規範OAS，且提供了相應的可視化編輯器可以編輯這個文檔以及對文檔格式進行校驗，文檔的存儲格式可是XML或者JSON形式的文件（後面簡稱API元文件），圍繞著API元文件框架提供了對API元文件進行可視化展示的工具，展示的時候可以自定義模板，展示的方式是瀏覽器的網頁形式(也就是一個 可交互的web系統），並且支持對AIP接口的在線的交互測試。同時社區還開發了一些集成框架，以便讓Swagger能和例如SpringMVC這樣的框架很好的整合，通過在Controller上寫註解就可以自動生成相應的API文檔。更有意思的是Swagger還提供了根據API元文件生成客戶端調用代碼和服務端Stub代碼的功能。

Swagger框架從宏觀上來看，我個人覺得可以分為三部分：

• 提供了一個編寫API文檔的規範 ，稱為OAS ，在規範中明確API的格式和一些編寫要素
• 提供相關的工具，對API文檔的編寫提供輔助。主要是這麽幾個項目 Swagger Editor、Swagger UI、Swagger Codegen、Swagger Inspector。
• 提供對各種流行語言和框架的集成，例如集成SpringMVC 的 springfox 框架

開源的API文檔工具框架——Swagger簡介