Laravel優勢：有許多強大套件，apiDoc也是其中之一。

相較於Postman，有以下優缺點：

優勢

• 版本控制
• 一套IDE就能同時寫code跟文件

缺勢

• 上手難度較高(指令較多、也須注意系統版本問題、綁定 domain url路徑)
• 美感
• 無法局部開放API文件內容，或許可透過git branch分支處理。

基本建置

step 1：從composer安裝套件

composer require --dev mpociot/laravel-apidoc-generator

step 2：再用php artisan vendor

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

在 config 資料夾內會多一個 apidoc.php 。

step 3：建立apidoc指令

php artisan apidoc:generate

• 更新apiDoc內容也是這指令 或 php artisan apidoc:rebuild 。
• 如果快取未清除，先下php artisan config:clear 試試。

step 4：進入網址

預設網址通常是 http://127.0.0.1:8000/docs/index.html

會看到類似的網頁

分別提供bash跟javascript語法的request指令->這點輸Postman。

範例指令

基本上只要是放在router的路徑都會顯示。

以下範例為 Task CRUD的 apiDoc指令介紹。

API分組指令

• @group 放在class之前，可將該class內的方法統整為一個group
• 可作說明，但未支援額外的markdown
  

單一API說明

以 store action為例

• 第一行 h1規格的標題
• 第二行 一般文字規格的說明
• ＠bodyParam 用空格區分 Parameter 名稱、 Type 資料型態、 Status 是否必需或選填、Description說明
• 如果在 ＠bodyParam 加上 Example後會出現在範例request指令中
• @response 可以填寫成功或失敗案例。不填寫http狀態碼預設為200

更新

• 一定要重下指令才會同步更新在apiDoc的網頁上
• php artisan apidoc:generate 或 php artisan apidoc:rebuild

參考資料
https://github.com/mpociot/laravel-apidoc-generator
https://beyondco.de/docs/laravel-apidoc-generator/getting-started/installation
https://www.youtube.com/watch?v=QQS5oEOguRU
https://packagist.org/packages/mpociot/laravel-apidoc-generator
https://ithelp.ithome.com.tw/articles/10226634