Laravel 8 開發中使用 swagger-php 3 生成文件

最近在新專案開發的過程中我發現 swagger-php 升級了版本，而且和以前的文件註釋寫法有了蠻多的差別。官方文件也寫的不是很詳細，在這裡我將結合自己封裝的案例將 Swagger-PHP v3.x 的一些用法分享給大家。

• 升級後的區別 Swagger-PHP v3.x Specification

• Swagger-PHP v3.x 官方文件

介紹

• 案例程式碼演示地址

• API 開發目錄

• 文件生成後效果

安裝

• composer require darkaonline/l5-swagger
• php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
• composer require laravel/sanctum

Swagger 可複用的公用引數

• 我會把文件的一些公共引數( 如 @OA\OpenApi , @OA\OpenApi, @OA\SecurityScheme)寫到 ApiController 裡面。程式碼如下

• 圖片對應

Swagger 請求引數

POST 請求

在 swagger-php 3.* 以前我們如果 Post 請求引數很多，那麼在控制器我們可能寫很多的註釋。導致程式碼特別冗餘。 swagger-php 3.* 我是透過 表單驗證 來解決這個問題的。同時程式碼也更清晰規範。

• 使用者註冊案列分享,程式碼如下

在上面程式碼中，我們看不到任何需要請求的引數，@OA\RequestBody 透過 ref 關聯到 #/components/schemas/RegisterRequest,而我們剛好有個表單請求類 RegisterRequest。在 swagger-php 3.* 我們可以把文件 post 引數的註釋放到表單請求類 RegisterRequest。RegisterRequest 程式碼如下:

• 生成文件效果

GET 請求

我們以獲取使用者列表和獲取使用者詳情，分別演示路由引數和請求引數註釋如何編寫。

• 路由引數案例(獲取使用者詳情)

• 請求引數案例(獲取使用者列表)

Swagger 返回引數

在 Api 返回的時候，有可能是列表，有可能是物件。如果物件引數特別多，按以前我們可能在控制器寫很多註釋文件，導致程式碼很難看，我在專案開發中是將返回的註釋寫到 API 資源 來解決這個問題。

返回陣列列表

• 獲取使用者列表案例

UserResource 程式碼

效果

返回物件

• 返回使用者詳情案例

從上面我們可以發現 UserResource 是可以複用的，當 @OA\JsonContent(ref="#/components/schemas/UserResource") 裡面有 type = array 返回的就是列表，不然就是物件。

異常返回

• 返回使用者詳情案例

• ApiNotFoundException 程式碼

總結

我是透過 API 資源 和 表單驗證 去拆解註釋，同時達到 API 開發目錄的規範。在我專案實際開發中，自己也基於這套規範收益良多。

本作品採用《CC 協議》，轉載必須註明作者和本文連結