L5 swagger 讓我們可以直接在laravel 原始碼中填寫所需要的文件生成指令，透過php artisan 直接產生api使用文件
並且帶有swagger-ui介面，可以直接查閱也可以在上面測試api
沒用過swagger? 可以直接到官網試試看精美的介面
https://swagger.io/tools/swagger-ui/
先說
L5 swagger 8.0版本以後已經不能將annotation獨立一個檔案寫了，需要跟controller寫在一起
請見作者回覆 : https://github.com/DarkaOnLine/L5-Swagger/issues/443
參考資料#
https://jamie-life-coding.site/2022/09/implement-l5-swagger-to-laravel/
安裝:#
laravel 5.5以後的版本只需要
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"舊版本請參閱參考資料連結
publish指令將設定檔複製到config資料夾中，可以依照需求來修改
撰寫Annotation#
annotation中描述的是每一隻API所要處理的事情、傳入的參數、回覆的內容的等等資訊
首先，打開 app/Http/Controller.php
在class Controller extend BaseController 上方加入
/**
* @OA\Info(
* version="1.0.0",//版本描述
* title="L5 OpenApi",//文件標題
* description="L5 Swagger OpenApi description",//文件描述
* @OA\Contact(
* email="developer@example.com"
* ),
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* )
* @OA\PathItem(
* path="/"
* )
* * @OA\server(//測試主機URL
* url = "https://api-host.dev.app",
* description="測試區主機"
* )
* @OA\server(//正式主機URL，可以不要寫
* url = "https://api-host.production.app",
* description="正式區主機"
* )
* @OA\server(//開發端主機URL
* url = "http://localhost/XXXXX",
* description="Localhost"
* )
* @OA\SecurityScheme(//如果API需要驗證token請加入
* securityScheme="Authorization",
* type="apiKey",
* in="header",
* name="Authorization"
* )
*/到這邊為止我們已經處理好swagger所需要的基本元素，透過以下指令就可以自動產生文件
php artisan l5-swagger:generate此時透過PROJECT_URL/api/documentation 就可以查看到swagger-ui產出的文件，大概像這樣子
當然，查看文件的路徑也可以在config/l5-swagger.php中的decumentatiopns.routes.api 去修改
接著開始是重點
針對每一支API請在每個class function中填入以下所需要的描述資訊
/**
* @OA\Get (
* path="/{name}",//router中的path
* tags={"find"},//給一個或多個tag方便搜尋用
* summary="這個api的summary",
* description="這個api的詳細說明",
* security={
* {
* "Authorization": {}
* }
* },
* @OA\Parameter (//輸入參數，如果有多個參數請輸入多個 @OA\Parameter
* name="帶入的參數名稱",
* description="帶入的參數說明",
* required=false,//是否必填
* in="path",//path 或 request 參數帶在網址或者呼叫傳入
* @OA\Schema (
* type="string"//參數型態
* )
* ),
* @OA\Response (//回應狀態，如果有多個回應狀態請填係寫多個 @OA\Response
* response=200,
* description="成功"
* )
* )
*/全部的API function寫完之後再重新產生一次文件就可以了
