前後端分離的實作中,會有遇到後端需要給前端 API 文件的需求,透過 phpdoc 的 PHP 工具可以將註解轉換成可讀的文件網頁,這樣基本只要把註解寫好文件也就差不多完成了(?)。
有幾點要注意:
- 執行的環境需要能夠使用 PHP,不推薦使用 composer 安裝(據官方稱很容易衝突)。
- 我建議先把設定檔做好,再依照設定檔案跑會比較輕鬆,這邊提供一組範例。
- 把設定檔放在根目錄外面是好習慣。
- 配置完成後,於相同目錄下執行以下指令產生文件:
phpdoc
- 文件中關於設定標籤 visibilities 有些錯誤,設定檔案的配置上建議還是要多試看看才知道。
- API 中常用的 post/get 方法,參數的引用不太適合用 @param,即便註解了也會顯示不出來,我查 stackoverflow 是推薦用 @uses 。
- 因為這是 php 文件,不是 HTTP API 文件,所以還是會存在溝通成本的,包含呼叫路徑的操作,這可能有賴於後續研究和嘗試自定義的調整。如果要生成 OpenAPI 格式,可以參考這個套件(有夠麻煩)。
—
我使用的是 phpdoc 3.0 版本。
安裝操作的部分,我使用的是 phar 安裝,好處就是可以裝到 global 環境:
首先先把 phar 檔案下載下來:
wget https://phpdoc.org/phpDocumentor.phar
變更權限:
chmod +x phpDocumentor.phar
然後改名,移動到 global 的環境上(這裡以 mac 為例):
mv phpDocumentor.phar /usr/local/bin/phpdoc
是否要移動到 global 環境取決於看有沒有要 project base ,這和 composer 的安裝類似,如果不是 mac 但不知道要移動到哪裡可以參考這個文件。
接著有基本參考 phpdoc 的文件就能運作了。他有很多功能,以下附上不負責翻譯:
而我是在 Codeigniter4 中實作,所以我會把路徑放在 ci4 的根目錄外面,假設 ci4 在 www/ 之中,我就放在外面,此時 source 的 dsn 會設定:
"./www/app/Controllers/"
而生成文件的設定也相對會設定在根目錄之外,參考範例。好處是避免文件因人為疏失變成公開的資安危機,壞處則是必須要額外設定路徑或網域來指向他提供給其他人閱讀。
而我的策略則是將該份生成文件納入版本控制之中,提供給前端,讓前端 pull 下來以後就直接用本地電腦打開來閱讀使用。
附上設定檔案範例(最後更新 2023-05-13):
推廣一下,要養成打註解的好習慣,不只是給未來的自己看,如今加上一個可以給前端看的服務,這樣打註解的動力應該會更高了。
參考資料:
PHP 註解的 tag 參考:
Phpdoc 設定文件:
Phpdoc 設定文件說明: