L5 Swagger 整合API文件到Laravel專案中
L5 swagger 讓我們可以直接在laravel 原始碼中填寫所需要的文件生成指令，透過php artisan 直接產生api使用文件
並且帶有swagger-ui介面，可以直接查閱也可以在上面測試api
沒用過swagger? 可以直接到官網試試看精美的介面
先說
L5 swagger 8.0版本以後已經不能將annotation獨立一個檔案寫了，需要跟controller寫在一起
參考資料
安裝:
laravel 5.5以後的版本只需要
|
1 2 3 |
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 上方加入
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
/** * @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所需要的基本元素，透過以下指令就可以自動產生文件
|
1 |
php artisan l5-swagger:generate |
此時透過PROJECT_URL/api/documentation 就可以查看到swagger-ui產出的文件，大概像這樣子
當然，查看文件的路徑也可以在config/l5-swagger.php中的decumentatiopns.routes.api 去修改
接著開始是重點
針對每一支API請在每個class function中填入以下所需要的描述資訊
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
/** * @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寫完之後再重新產生一次文件就可以了
