文章目錄
前言
開篇首先給出結論，目前tornado與swagger的集成程度並不高，如果想要通過swagger自動生成API，需要對其進行深度定製，下面給出調研的一些結果
商業項目中，隨着迭代的速度越來越快，與之相應的文檔維護變得越發麻煩。
久而久之，項目文檔與當前項目代碼版本差的越來越遠，便失去了其價值
本地調研的目的是找到一種能夠高效維護API文檔的解決方案。
文檔的好處與“壞處”
一個項目中，文檔是不可或缺的組成部分，其中比較重要的有：
- API接口文檔
- 業務說明文檔
好的文檔可以：
- 降低項目依賴人的重要性，不會因爲人員流動而導致項目無法正常運轉，也可以讓接手項目的人，快速上手；
- 可以提高人的寫作、語言組織能力；
- 可追溯性，不至於有問題無從查起，做到有理有據；
當然寫文檔也有“壞處”，那就是費時費力，如果文檔不及時更新，甚至會給後來接手項目的人造成不必要的困擾。
總的來說，文檔是一定要寫的，那麼問題就轉變爲：如果高效的編寫和維護文檔
幾種比較流行的工具
confluence
Confluence是一個企業級的Wiki軟件，可用於在企業、部門、團隊內部進行信息共享和協同編輯。
說了是Wiki軟件，那麼基本是什麼文檔都可以往上面放，接口文檔自然不在話下，並且能夠團隊協同編輯，內置的富文本編輯器也是十分的好用，誰用誰知道～
關鍵是上手完全沒有任何難度，如果目前還沒有使用類似的文檔管理系統，那麼confluence非常值得一試
這裏就不多詳細描述了，網上教程很多，貼一個博客鏈接，有興趣的可以自己摸索一下
But，儘管confluence很好用，它仍然沒有解決文檔維護困難的問題，你還是要手動在編輯器上自己寫文檔。
Ray2
當我看到Ray的時候，這個工具已經出到2了，由於老版本的ray已經不在維護，所以這裏就直接介紹Ray2
Ray2相較於confluence，其功能更加的專一，它就是一個專門用來管理API接口文檔的平臺
首先，Ray2是開源的，由阿里媽媽前端團隊維護（阿里出品，必屬精品～）
這是Ray2的github地址
同樣的上手非常簡單，並且可以無需安裝直接體驗，地址就在上面github的README下面
簡單來看一下界面
從概念上來講，Ray2提供了倉庫–>模塊–>接口的層級，一個個倉庫就相當於項目，每個項目又按模塊進行劃分，而模塊下面的自然就是一個個接口文檔了。
從編寫方式來講，Ray2提供了非常高效的API文檔模版，我們只需要往模版裏面填寫數據，就可以快速編寫API接口文檔，這相較於在confluence下一個字一個字的碼，無疑更進了一步。
Swagger
使用Ray2維護API文檔已經十分高效了，但是歸根結底，還是需要人去手動維護的，那麼有沒有更加強大，便捷的文檔維護方式呢，答案是YES，就是下面即將介紹的 Swagger
Swagger是一種Rest API的 簡單但強大的表示方式，它是標準的，語言無關，這種表示方式不但人可讀，而且機器可讀。
可以作爲Rest API的交互式文檔，也可以作爲Rest API的形式化的接口描述，生成客戶端和服務端的代碼。
網上找的Swagger生態使用圖
Swagger上手難度比前兩者要高出一些，當時它強大的功能足以讓我們下定決心去使用它。
基本用法：編寫Swagger API Spec
首先說說，swagger-editor，它是swagger提供的在線文檔編輯器，編輯器傳送門，長這個樣子
左邊是編輯器，我們可以通過編寫Swagger API Spec ( yaml風格 ) 的文檔，在右邊的swagger-ui上直接渲染出相應API文檔
其中Swagger API Spec就是Swagger提供的用來描述Rest API的語言。
Swagger API Spec對Rest API的每一個操作的請求消息的參數（Path,Query,Body,Form），響應消息的狀態碼和消息體的json結構都進行了詳細的描述。不僅可以供給使用API的開發者學習，而且是對Rest API接口的形式化的抽象。
關於Swagger API Spec，如果想了解更多的話，可以戳這裏
和rap不同的是，渲染後的頁面不可以編輯。但是可以直接在頁面上模擬真實的請求操作。
生態圖裏面另外幾個東西就不多做介紹了，swagger-codegen倒是有點說法，這個工具的功能就是根據接口文檔生成相應的代碼。
既然可以通過文檔生成代碼，那當然可以通過掃描代碼自動生成API文檔嘍～
高級用法：集成後自動生成API文檔
通過在項目代碼中進行一系列的配置，我們可以通過swagger直接生成項目的API文檔，這下牛逼了，文檔跟着代碼走，代碼更新，文檔自動更新，不用手動維護了。
這纔是swagger的正確使用姿勢～
由於各個項目，框架的配置方式不同，這裏就不展開來說了。目前以python框架作爲開發的項目中集成的比較好的有：Django，Flask，Fastapi
關於Tornado集成Swagger
比較遺憾的是，Tornado對於swagger的集成程度並不高。如果想要在Tornado中使用swagger的話，只能在接口方法的__doc__中編寫Swagger API Spec，像這樣：
這無疑是一個非常痛苦的過程 : (
使用到的第三方庫，有興趣的可以看看，github tornado-swagger
或許我們可以針對Tornado集成swagger進行一些定製，使之能夠自動生成API文檔，但從目前來講，要完成這個目標，需要比較大的工作量。
總結
我們已經看了幾種工具，都從不同程度上幫助我們提升了文檔維護的效率，那麼到底該選擇哪一種呢？
我的建議是： confluence + (Ray2 or Swagger)
- 從功能上看，confluence是非常推薦使用的。
- Ray2和Swagger，則根據情況二選一即可，畢竟API文檔還是需要統一管理的
根據不同的場景，總有一款適合你～
參考文檔
Swagger.io
Swagger：Rest API的描述語言
Swagger Editor
ray2
tornado-swagger
