前後端分離的實作中，會有遇到後端需要給前端 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 設定文件說明：
