OpenAPI初體驗

問題的一開始源於客戶和服務部門抱怨個人REST API文檔寫得很差，而後又瞭解到 django rest framework 利用 coreapi 能自動生成文檔，再就是看到 swagger.io 上說得天花亂墜的，OpenAPI文檔寫完後，能夠生成40種語言的客戶端代碼（用戶都不用文檔了，代碼都生成了！！），外加N種服務端stub代碼，另外演示文檔真心漂亮。因而我開始了研究 REST API specification的各類語言了，這裏簡單總結備忘下。

API specification

API sepecification有不少種語言，主流的有3種

• OpenAPI (swagger)
• RAML
• API blueprint

我最開始研究的是openapi，沒寫幾個endpoint我就放棄了，層次太深，縮進了幾層以後，徹底不知道本身在什麼地方了。

我立刻轉去研究 api blueprint，這個挺好，有專門的emacs apib-mode，並且層次沒有那麼深，看起來更直白一點，甚至本身搞了 MSON 的規範，總之寫起來更像是給人看的，而不是給機器看的。apib的工具相對較少，好在能夠轉成 openapi，而後再生成代碼等等 。不過，好景不長，稍微複雜一點的API表達能力就有限了（須要複製、粘貼），表達得也不是那麼直白。

以我python程序員的角度看問題，這種東西應該由python來寫，每一個可利用的模塊定義成function或class，而後引用一點，這樣也能夠將api spec拆分紅小塊，又要看，又好維護。事實上，肯定有一個叫 openapi 的package，完成了這件事情，能夠用它來寫，不過只支持 2.0，就沒有仔細研究了。

我沒有再去研究RAML，由於它也是yaml，因此層次問題確定也存在，我去試也下基於Eclipse的KaiZen編輯器，層次問題仍然存在，雖然有outline、補全提示和template，但層次問題仍然很差解決。聽說 jetbrains 平臺也有相似的插件，我沒有去試。

正當我鬧心的時候，我搜索到了這麼一篇文章，說的是使用json ref來把swagger文檔拆分紅多個，雖然文章結尾給出的方法 json-refs resolve沒法達到他說的那樣，可是思想是好的，因而我本身花一天時間寫了一個工具，實現了文章上說的方法，而且不會展開local ref，在openapi最後文檔中仍然保留對schema的ref。

Swagger-tools

openapi號稱有不少工具，而且官方網站上也一直在宣傳最新的3.0標準，因此我本身選擇了3.0，而後很快就掉坑裏了（一下子再說）。

先說下個人工做方式，我使用emacs管理一個全是yaml文件的工程，而後使用$ref把他們都link起來。一開始我每次合併成一個文檔後，而後拿swagger-editor打開，看看哪裏有錯誤，再改，可是這樣很是得慢，由於swagger-editor是基於網頁的，本地文件變了不會自動加載到編輯器中去，還得每次點。官方有個swagger-validator貌似只支持2.0的，即便支持3.0，估計我也搞不太明白，由於不習慣nodejs那套東西，終於發現python也有一個叫 openapi-spec-validator的東西，雖然作得粗糙了點，可是仍然是能夠用的，很方便集成到個人工做流中，每次保存時合併到一個文件中，而後調用 validator 檢查，很是好。

無論能不能搞明白nodejs，swagger-editor和swagger-ui是必需要使用的工具，幸虧官方提供了docker container，而後我再寫一個alias，就能夠在bash中使用了，以下

alias swagger-ui='echo "http://localhost:8000" && docker run --rm --name swagger-ui -p 8000:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $PWD:/app swaggerapi/swagger-ui' alias swagger-editor='echo "http://localhost:8080" && docker run --rm --name swagger-editor -p 8080:8080 swaggerapi/swagger-editor'

 這裏假設了我合併以後的文檔名稱爲 openapi.yaml

生成代碼

當我很興奮了寫了不少endpoint以後，我想試試生成代碼這個功能，很不幸，真的被坑了。swagger-codegen穩定版本竟然不支持 3.0版本的openapi，只支持到2.0，抱着試一試的心態去看看了正在開發的swagger-codegen的snapshot，太讓人失望了，只支持幾種語言，竟然沒有python也沒有go，大約都是java和js。

因而我沒有辦法，又去看了下2.0版本的openapi規範，真心不如3.0，着實沒有學習的動力，萬般無奈下，處處找3.0轉2.0找工具，只有一兩種可選，並且不是收費，就是很差使。最後終於被我在github上發現了api-spec-converter，能夠把3.0轉成2.0。在解決了如何不使用root用戶全局安裝npm module後，才把它安裝上了。而後使用命令行

api-spec-converter -f openapi_3 -t swagger_2 openapi.yaml > swagger.json

 

就能夠轉換，我也覺得就這樣結束了呢，使用少的東西，坑本身多，因爲2.0的表達能力不是很強，外加轉換工具備BUG，因此我列舉了下注意事項以下

• path不能有summary和description，這些應該放到operation裏（即get/put/post等裏）
• 只支持一個server
• components裏只能有schema，不能有其餘的，如parameters，responses
• parameter最好不要有local ref，api-spec-converter不能正確處理
• parameter應定義在operation級，即get/put/post下面，公共的parameter，工具處理不正確
• additionalProperties不支持，工具也沒有自動地刪除它
• readOnly的properties不能具備required屬性

終於生成了2.0的spec，有空再試codegen的質量吧。坐等codegen支持3.0，或者哪天我本身研究個Python或Go的工具吧。

總結

無論怎樣，swagger-ui 我仍是很喜歡的，api自帶swagger-ui這樣的界面，集文檔和嘗試一身，對用戶很是友好，即便不能生成代碼，也是不錯的選擇。