Laravel 套件 Scramble 介紹
分類
說明
Scramble 是 Laravel 的 OpenAPI (Swagger) 文件產生器。它會自動為您的專案產生 API 文件,無需您手動編寫 PHPDoc 註釋。
在我寫這篇文章時,此套件應該還算是開發階段,雖然好用,但功能不是很完整,有些 API 文件無法自動生成,但大部分的內容,尤其是請求的部分都還算完整。
預覽
安裝
你可以使用 composer 安裝 Scramble:
composer require dedoc/scramble
使用方式
請參考官方文件,最主要的部份是處理 Requests, Responses。
以下我將簡單說明一些使用方法,完整內容請參考官方文件。
請求
如果使用 Laravel 表單驗證功能也可以自動生成 api 文件。
php artisan make:request StorePostRequest
建立 StorePostRequest 表單
範例如下:
/**
* Get the validation rules that apply to the request.
*
* @return array<string, \Illuminate\Contracts\Validation\Rule|array|string>
*/
public function rules(): array
{
return [
'title' => ['required', 'unique:posts', 'max:255'],
'body' => ['required'],
];
}
手動記錄請求參數
use App\Models\Location;
class LocationsController
{
public function update(Request $request, Location $location)
{
$request->validate([
/**
* The location coordinates.
* @var array{lat: float, long: float}
* @example {"lat": 50.450001, "long": 30.523333}
*/
'coordinates' => 'array',
]);
}
}
@example
應該是字串或有效的 JSON。
手動描述字段的用法
對於自動欄位類型解析不起作用,或需要向欄位新增描述的情況,可以新增 PhpDoc 註解:
return [
'id' => $this->id,
/**
* @var string $content The content of todo item, truncated.
* @example "example"
*/
'content' => $this->someMethodCall(),
];
修改 EndPoints 目錄
所有 EndPoints 均以控制器名稱組織在資料夾中。
您可以使用 PHPDoc 中的 @tags
在控制器層級新增自己的標籤。這會將來自該控制器的所有路由放入此資料夾中。
/**
* @tags Media
*/
class DownloadMediaController
{
public function show(Media $mediaItem)
{
return $mediaItem;
}
}
你會在 EndPoints 看到目錄從 DownloadMedia 改成 Media。
打開文件
你可以直接線上打開文件。
{domain}/docs/api
- 文件的 UI 檢視器。
例如本機端: http://127.0.0.1:8000/docs/api
。
設定
可選,您可以發布套件的設定檔:
php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"
在 config\scramble.php
設定 Scramble。
中介層
預設只開放 local 環境,你可以用兩種方式授權閱讀權限。
使用 Gate
因為 Scramble 中介層已經幫你允許 viewApiDocs Gate,你只需定義它即可,適合有使用 User Gate 的專案。
app\Providers\AuthServiceProvider.php
<?php
namespace App\Providers;
use App\Models\User;
use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
class AuthServiceProvider extends ServiceProvider
{
/**
* Register any authentication / authorization services.
*/
public function boot(): void
{
Gate::define('viewApiDocs', function (User $user) {
return in_array($user->email, ['admin@app.com']);
});
}
}
改寫中介層
在 Scramble 設定修改 middleware 使用自定義中介層,適合沒有使用 User Gate 的專案。
config\scramble.php
<?php
return [
'middleware' => [
'web',
// 放置自定義 middleware
],
];
參考
一杯咖啡的力量,勝過千言萬語的感謝。
支持我一杯咖啡,讓我繼續創作優質內容,與您分享更多知識與樂趣!