又是一個 laravel-swagger 套件

Swagger 現在正式名稱其實是 OpenAPI，簡單來說就是一套用來描述 API 規格的格式標準。

由於算是成熟的標準（本文撰寫時已經來到 v3）所以周邊生態相對成熟，也有不少套件可以用。

本文提及之「UI」及「Editor」單獨出現沒其他說明的話，皆指稱「Swagger UI」及「Swagger Editor」

為什麼還要再自己造一個輪子？

最近在工作上開始採用這套標準來寫 API 文件/規格書，但卻發現有一些問題（至少以我自己看是問題，可能能力不足或剛好目前情況來看是個問題）。

首先，Swagger 官方原先就是以「網頁」的形式為主（例如： UI 和 Editor）所以套件都是圍繞在 npm 上。雖然 Laravel 根目錄上就有 package.json，但作為完全前後分離的 API 專案來說，可能不是一個好方法。

第二點由第一點延伸，故要找非官方開發的方法來進行。目前我自己找到的（也是最有名最多人用的）是 L5-Swagger。這個套件特色是什麼都包好了，包含依照註解自動產生 OpenAPI 文件（基於 swagger-php 實作）以及整合 Swagger UI。不過 swagger-php 文件可能是我不太會看，註解弄了半天，我認為我直接撰寫原始 OpenAPI 規格文件還比較快。而 L5-Swagger 當然可以這樣用，但多安裝一個 swagger-php 都沒用到，根本浪費我的硬碟空間，這是第二點。

由於只想要有整合 UI 的部分就好，找到了 laravel-swagger-ui。原本想說事情可以告一段落，但實際使用下去才發現，他對 yaml 的支援根本有問題（手寫 JSON？饒了我吧）。一看也有人發出 issue。可是套件維護者們似乎沒有想修的意思，我自己看了下他們的程式碼，發現對 yaml 的支援應該是半殘，有一部分直接寫死（hard code）是 json 檔案了阿阿阿！這就是第三點，現有比較符合需求的套件看起來好像不太行。

最後，在自己簡單摸索下，發現其實整合並不難。考量到日後其他專案也可以採用，就在下班後興沖沖的做了一個簡單的套件：laravel-swagger（菜市場名阿）

套件介紹

https://github.com/hms5232/laravel-swagger

特點

套件支援 autoload，故在 README 中寫了兩種安裝指令，可以自行依照是否會在生產環境下使用決定要使用哪種安裝方式。

此套件許多東西可以從 .env 中設定或加以控制：

  • 總開關控制是否啟用，故也可以僅在需要的時候才啟用套件
  • 可自訂 OpenAPI 的入口點文件
  • 可自訂 OpenAPI 文件存放位置
  • 可自訂 OpenAPI 文件暴露出的 route 路徑（支援資料夾）
  • 可自訂 Swagger UI 的 route 路徑
  • 可自訂 Swagger UI 的 版本
  • Swagger UI 預設開啟就讀取你的文件
  • 可自訂 Swagger Editor 的 route 路徑
  • 可自訂 Swagger Editor 的 版本
  • Swagger Editor 預設開啟就讀取你的文件
  • 可單獨啟用 UI 或 Editor 其中之一
  • 其他部分努力開發中

實作細節

其實拆開套件會發現邏輯很簡單，大致上就是配合 Laravel 做一些修改來整合 UI 和 Editor 而已：

  1. 做一個 route 可以請求到 OpenAPI 文件們
  2. 做一個 view，裡面是修改後 UI 的 dist 版本，然後是一個指到這個 blade 的 route
  3. 同第二點，Editor 也如法炮製

雖然用說的很簡單，實際上也花了不少時間撰寫和測試。歡迎有興趣的朋友試用看看，好用的話也幫我按個 星星吧。

此套件不支援依註解自動產出文件的功能

結語

話說在興沖沖的寫好並準備要發布 0.1.0 版的時候，packagist 告訴我還有其他 36 個同名的套件，我一看差點沒暈倒。隨便抽了五個同名套件，都不知道在幹嘛，所以最後還是發布了我自己寫的這個套件。

然後因為不知道這篇文要放什麼圖比較好，所以放了完成今年 hacktoberfest 後他給的獎勵之一的圖。

結語怎麼好像變成了題外話？算了都可以啦，大家趕快去試試看這個套件吧！有什麼想法歡迎使用 issue 功能提出，可以使用正體中文喔！