如何使用laravel+l5-swagger製作一份api文件
介紹
對一個後端工程師來說，一個功能開發/修改流程中所遇到其中一個環節不外乎是與前端說明你的API如何使用，像是需要前端傳什麼資料、我會回完什麼資料…等內容。
而在這過程中使用通訊軟體或口頭上的溝通確實快又有效，但人總是健忘的，下一秒可能就忘記要怎麼使用這接口。
Swagger提供開發者可以快速完成API文件的撰寫需求，透過有結構性的文件以及搭配版本控制，能有效提升開發者之間對於新/老接口的使用以及追逤。
目前市面上主流框架及程式語言也支援Swagger撰寫，下面則將介紹如何在laravel 中安裝 DarkaOnLine/L5-Swagger與設定
使用環境
- L5-Swagger Version: 7.0
- PHP Version: 7.2.8
- Laravel Version: 7.30.4
- darkaonline/l5-swagger
安裝步驟
- 透過composer安裝 darkaonline/l5-swagger
composer require "darkaonline/l5-swagger:7.*"若laravel版本≥5.5無需執行下列步驟
開啟 app/Providers/AppServiceProvider 在 register 中新增
$this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);或者開啟 config/app.php 在 providers 區中增加
L5Swagger\L5SwaggerServiceProvider::class,2. 執行命令以生成所需檔案
php artisan l5-swagger:generate如果懶得手動打指令，也可以設為自動生成功能，方法如下：
# 開啟 config/l5-swagger.php, 並調整為true'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', false),
3. 訪問 /api/documentation（默認路由）
也可以視需求調整路由
# 開啟 config/l5-swagger.php, 找到routes['api']
'routes' => [
/*
|---------------------------------------------------------------
| Route for accessing api documentation interface
|---------------------------------------------------------------
*/
'api' => 'api/documentation',]
開始編寫註解（annotation）
The goal of swagger-php is to generate a openapi.json using phpdoc annotations.
根據官方的說法，我們需要透過編寫phpdoc語法讓套件產生swagger所需要的openapi.json文件
常見有兩種做法：
- 跟著Controller綁定，將對應的接口內容與function編寫一起。
- 另外開啟資料夾，專門存放相對應的內容。
後面會使用方法一進行介紹，其中對於方法二的使用與介紹可參考@hosomikai 大的文章：
以Laravel為例，一般我會建立一個BaseController作為基類，並讓其他的Controller繼承做使用。
而對於整份swagger文件的基本訊息我也習慣放在這，例：
/**
* @OA\Info(
* version="1.0.0",
* title="木木食器",
* description="接口文檔",
* @OA\Contact(
* email="watshing625@gmail.com"
* ),
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* ),
* @OA\Server(
* url="http://127.0.0.1/api"
* ),
*
*/
class BaseController extends Controller {
// ....
}此時先別著急，我們必須設定至少一個接口內容，例
/**
* @OA\Get(
* path="/api/resource.json",
* @OA\Response(response="200", description="An example resource")
* )
*/最後重新訪問頁面，可以看到
其中包含了剛剛編寫的基本文件資訊
以及我們剛剛臨時放上去的接口
分享一個我在安裝時因為laravel優化功能而踩的坑
當時我在使用composer安裝l5-swagger套件，直接報錯。
argument 2 passed to l5swagger\generator::__construct() must be of the type string, null given, l5swaggerserviceprovider.php on line 74
但當時想說怎麼可能！我好歹也是照著官方說明來操作，不論是步驟還是版本需求的。中間還刪除重新安裝了幾次…
後來找到官方issue發現是由於cache導致的問題，由於在那之前我使用了laravel優化功能，導致config檔被寫入暫存
php artisan optimize最後解決方法是只要刪除或更新它後重新執行命令即可
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"當然如果想要重新安裝也是個辦法。。。
最後謝謝您的收看，以上就是Laravel中使用darkaonline/l5-swagger 基本安裝與設定的步驟。關於更多的使用方法與介紹，後面會透過其他篇再詳細說明。
