API文檔化開發實戰

作者toyld 豈安科技搬運代碼負責人

主導各處的挖坑工作，擅長挖坑於悄然不息，負責生命不息，挖坑不止。

1 序幕: 痛苦的來源

情景

私有化部署需要調試客戶部署的機器的時候,部署的環境並不會部署調試工具, 當你做好最後無奈只能一邊查curl文檔一邊敲命令的心理準備的時候，你發現curl命令還沒有裝。然而客戶的內網機器不允許外網……

2 續章: 解脫之法

這些問題說到底只是http協議本身，前、端後開發人員三者之間確實存在巨大的鴻溝，導致溝通成本巨大。這裡就需要我好好地來潤滑一下了。我採取的方法是：約定好最常使用的一個公司範圍內最小語義子集充當潤滑劑,，即API文檔化。

2.1 API文檔，前後端並行開發

需求進來之後，前後端雙方溝通之後約定介面，並提供api文檔化，api文檔單獨進行版本管理，與之產品的設計原型版本大致同步(不一致的情況只有必須調整介面的技術重構)，然後前後端並行開發。

2.2 調試

如果說api文檔來驅動開發很理想化，那麼根據api文檔生成同一份請求和返回的mock server則為這種開發流程牢牢的扎穩了腳跟，這裡我們實現的mock server不僅僅是常見的接個請求然後返回一個寫死http報文, 而是說同樣能夠識別我們的文檔, 生成對應格式的請求和返回http報文, 是否隨機、還是指定特定的值，用來做錯誤或者正確的功能測試都沒有任何問題, 到此不僅是前後端的人了解了api, 前後端的代碼也真正的識別了api ,在拋開了前後端工程師思想上溝壑之後，當我們的注意力都能聚焦在真正的bug上的時候，我都不敢想像這幅美景，太美了~(事實上回想, 不需要前後端共同開發聯調靠喊，確實省了很多心)。

2.3 售後

部署的環境並沒有趁手的工具的問題，加之如果是遠程連接的話，一般都會很慢，這種情況下調試無疑是低效且痛苦的。為了解決在原始環境下調試的問題，我們將swagger-ui的靜態頁面跟隨產品發布，並且各個部件提供了與之兼容的API的文檔，能夠在網頁上讀取API文檔直接調試API。

我們現在考慮將swagger-ui的界面提供給售後、實施的同事，甚至客戶來操作，拋開命令行，通過頁面配置參數的方式來調試api介面發現問題，就不需要每次叫研發來確定發現問題了，而是直接通過售後的具體的api訪問的返回來直接確定問題,然後解決了。

3 終章: 動手

談完了YY的理想，我們來看看怎麼將這些東西一步步落地到現實。

API標準： https://github.com/OAI/OpenAPI-Specification ，因為業務場景沒有特定到有成熟的restful api的標準，所以我們選擇了盡量通用且工具齊備的OpenAPI。

3.1 從代碼中提取api文檔,提供整套後端的api文檔給swagger-ui的頁面。

• Java： jetty有一個現成的插件，能夠很方便的從代碼中生成api的文檔。
• Python：因為Python的動態語言屬性，不能直接效仿java的玩法，所以我給tornado做了一層類似django的中間件的內部python庫出來， 在application實例上掛上兩個api介面, 來提供api版本、和完整的api文檔。

api版本介面是用來檢查前後端之間是否說的是同一版本的api，盡量在越早的時間點發現錯誤。python提供api文檔的方式是通過解析註冊到application實例上所有路由對應的視圖函數(或者說請求處理函數)中的_doc_來實現的，動態生成的方式免去了修改之後多餘的生成步驟。

3.2 識別api文檔的mock server

這裡是前端自己用nodejs擼了一個識別OpenAPI的mock server, 將OpenAPI文檔轉換到http報文做了這麼一層轉換, 並在api的版本管理基礎上，將各個版本的api文檔做了可視化的展示，方便的生成對應的請求、返回http報文來測試功能、錯誤返回的檢查，調試結束之後，改一下api所在的ip地址就可以無縫遷移成生產狀態. so easy~

3.3 swagger-ui的定製

• token的驗證; 兼容原始的登陸cookies方式, 如果在非登陸的瀏覽器裡面訪問，需要先從login介面拿到token，或者登陸獲取cookies, 因為就算是客戶內網，各個部件之間的訪問安全也是我們關心的, 下一步就是說跟客戶的認證系統掛鉤，而不是走自己單獨的一套認證。
• 編輯header, http報文; 用swagger-ui的靜態頁面就是為了能夠省去操作命令行、依賴命令行命令的弊端，但是原生的swagger-ui並不支持修改請求的http報文，為此我們做了一些定製化的開發。
• 一些易用性的定製化, 比如: 支持多個同名查詢參數.

到此, 我們就搭建了一個由api文檔串聯起來的整個開發、測試、售後的完整流程。