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

　　初次接觸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 框架