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
    ],
];

參考

• PHPDoc Types
• Scramble