API 文檔神器 Swagger 介紹及在 PHP 項目中使用
Swagger 是我目前用過的最優秀的 Api Doc 協議沒有之一。它與其他 Api Doc 協議(如apidocjs)最大的差別在於,Swagger 不僅僅可以定義 Api 的 Route / Request Param 和 Response,還可以定義 Definitions Object / Security Definitions Object 以及 Reference Object。
以一個電商項目為例,系統里有 商品(Product)和 訂單(Order)兩個 Model,其中 Order 有一個 欄位用於關聯對應的商品;有兩個介面,一個是獲取商品詳情 ,另一個是獲取訂單詳情 ,為了減少Api請求數量,在獲取訂單詳情時我們希望同時返回對應的商品數據。
如果我們用 apidocjs 來寫的話,會是類似下面的注釋
可以看到 Product 的欄位在兩個介面的注釋里各寫了一遍,這就很繁瑣;另外一個更嚴重的問題是,如果未來 Product 表的欄位發生了增減,我們需要去修改每一個會輸出 Product 的介面的注釋,更繁瑣而且容易遺漏。
所以我們需要有一個可以定義 Model 欄位的功能,這就是 Swagger 的 Definitions Object,我們事先將 Product 和 Order 定義成 Definitions Object:
在定義 Order 的 product 欄位時,我們使用了 ,也就是 Reference Object,這就是告訴 Swagger,Order 的product 欄位指向了 Product 的定義。
再來看看 Route / Request Param 和 Response 在Swagger 中怎麼寫:
通過 完美解決了增減欄位需要修改多處的問題。
我在第一次使用 Swagger 的時候,雖然被其強大的定義功能所折服,卻又對寫 Swagger 文檔極其的厭惡,因為官方提供的 Swagger Editor 速度不僅慢,還時不時出錯,明明寫對了文檔格式非要告訴我有問題,只能刷新頁面重新載入。
直到最近發現了一個項目 swagger-php,通過注釋的方式來生成 JSON 格式的 Swagger 文檔,只需要通過 函數掃描一個目錄下所有 PHP 文件的注釋 (可以創建一個完全只有注釋的 php 文件來放一些與 request / response 並無直接關聯的定義,比如 Security Definitions Object)。
有了 JSON 格式的文檔之後,配合 Swagger UI 就可以展示出非常美觀的 Api 文檔了,可以看這個 Demo,還支持在文檔頁面直接發起 Api 請求,大大的方便!
點擊展開全文
※你不是不努力,而是不懂選擇
※Laravel artisan optimize 源碼解讀
※在laravel中使用Symfony的Crawler組件分析HTML
※通過 PHP OPcache 讓你的 Laravel 應用運行速度飛起來
※RED_HAWK:基於PHP實現的信息收集與SQL注入漏洞掃描工具
TAG:PHP技術大全 |
※CPU優化神器Steam CPUcores
※SSH客戶端神器MobaXterm,該拋棄putty、Xshell和CRT了
※黑眼圈遮瑕神器,Better Than Sleep BOBBI BROWN即時無痕遮瑕蜜全新上市
※iOS繪畫神器《SketchBook》
※神器升級 Blackmagic發布BMPCC二代相機
※谷歌Night Sight正式登陸Pixel 3/3 XL:夜拍神器
※GPU+CPU Turbo 手游神器榮耀Note10是怎樣煉成的?
※iPhone X必備神器:AirPower底座下月開賣
※iPhoneX必備神器 AirPower無線底座來了
※Mac效率神器Alfred系列教程-iTunes Mini Player
※Pytorch神器
※iPad建模神器 —「Shapr3d」
※文獻管理必備神器之 Endnote 入門介紹(送 PPT)
※VR繪畫神器!Massless Pen觸控筆試玩
※調侃馬拉松神器NIKE EPIC REACT FLYKNIT真假PK
※Apple Watch 神器!自由重刷升降級傳輸工具iBUS S2
※最適合冬日抱團取暖的「神器」來了Here Comes a Great Heater in Winter
※Apple Watch Series 4 堪稱救命神器,可惜在中國行不通
※萬興科技PDFelement參展GMIC,橫掃歐美的數字文檔管理「神器」有何魅力?
※Photoshop調色神器!一鍵模擬Vsco和Instagram濾鏡效果