8.1版之前可以將所有的文件集中在一個目錄下，會自動掃描app目錄下的文件，但從8.1之後版本文件只能寫在controller裡面.
下面為8.1版以後版本必須寫在controller.php裡面
/**
* @OA\Info(
* version="1.0.0",
* title="API 文件",
* description="API 文件."
* @OA\Contact(
* email="roger@icarry.me"
* ),
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* ),
* @OA\PathItem(path="/app"),
* @OA\Server(
* url="",
* description="目前伺服器"
* ),
* @OA\Server(
* url="https://api.localhost",
* description="開發用測試機"
* ),
* @OA\SecurityScheme(
* type="http",
* description="Login to 前台-使用者 get the authentication token",
* name="authentication",
* in="header",
* scheme="bearer",
* bearerFormat="JWT",
* securityScheme="webAuth",
* ),
* @OA\SecurityScheme(
* type="http",
* description="Login to 後台-管理者 get the authentication token",
* name="authentication",
* in="header",
* scheme="bearer",
* bearerFormat="JWT",
* securityScheme="adminAuth",
* ),
* @OA\SecurityScheme(
* type="http",
* description="Login to 商家後台-管理者 get the authentication token",
* name="authentication",
* in="header",
* scheme="bearer",
* bearerFormat="JWT",
* securityScheme="vendorAuth",
* ),
*/下面為8.1版以後版本必須寫在相關的controller.php裡面範例
/**
* @OA\Tag(
* name="機場地址",
* description="iCarry 機場地址 API",
* ),
* @OA\Get(
* path="/web/v1/airportLocation",
* operationId="webAirportList",
* tags={"機場地址"},
* summary="前台-機場地址資料列表",
* description="1. 輸入 to_country_id 取得該國家機場地址資料。
2. 輸入 lang 參數只能取英文資料，無英文資料則以中文替代。
3. name 欄位為顯示，value 欄位為帶入訂單中的資料。",
* @OA\Parameter(
* name="to_country_id",
* description="國家id",
* required=true,
* in="query",
* @OA\Schema(type="integer"),
* @OA\Examples(example="台灣", value="1", summary="台灣"),
* @OA\Examples(example="日本", value="5", summary="日本"),
* ),
* @OA\Parameter(
* name="lang",
* description="語言代號",
* required=false,
* in="query",
* @OA\Schema(type="string"),
* @OA\Examples(example="null", value="", summary="不選擇"),
* @OA\Examples(example="英文-en", value="en", summary="英文語言代號-en"),
* @OA\Examples(example="日文-jp", value="jp", summary="日文語言代號-jp"),
* @OA\Examples(example="韓文-kr", value="kr", summary="韓文語言代號-kr"),
* @OA\Examples(example="泰文-th", value="th", summary="泰文語言代號-th"),
* ),
* @OA\Response(response=200,
* description="Success, 取得該國家機場地址資料",
* @OA\JsonContent(ref="#/components/schemas/AirportLocationSuccess")
* ),
* @OA\Response(response=400,
* description="Error, appCode 999, 參數錯誤/參數不存在",
* ),
* ),
* @OA\Schema(
* schema="AirportLocationSuccess",
* type="object",
* title="前台-機場地址資料列表欄位說明",
* @OA\Property(property="status",type="string", example="Success",description="狀態"),
* @OA\Property(property="message",type="string", example="null",description="回應訊息"),
* @OA\Property(property="total",type="string", example="10",description="資料筆數總計"),
* @OA\Property(
* property="data[]",
* type="array",
* @OA\Items(
* @OA\Property(
* description="名稱 (顯示)",
* property="name",
* type="string",
* example="Taiwan Taoyuan Airport - Terminal 1 Departure Hall",
* ),
* @OA\Property(
* description="值 (value 帶入資料中)",
* property="value",
* type="string",
* example="桃園機場/第一航廈出境大廳門口",
* ),
* ),
* ),
* ),
*/目前暫時找不到方法將所有文件集中，故先鎖住用舊版方式
composer require "darkaonline/l5-swagger:8.1"