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

標籤：blog   線上   系統   整合   mvc   注意力   自訂   https   UI   

　　初次接觸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簡介