當前位置:
首頁 > 知識 > API 文檔神器 Swagger 介紹及在 PHP 項目中使用

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 請求,大大的方便!

點擊展開全文

喜歡這篇文章嗎?立刻分享出去讓更多人知道吧!

本站內容充實豐富,博大精深,小編精選每日熱門資訊,隨時更新,點擊「搶先收到最新資訊」瀏覽吧!


請您繼續閱讀更多來自 PHP技術大全 的精彩文章:

你不是不努力,而是不懂選擇
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濾鏡效果