Документування автентифікації API в Laravel за допомогою Scramble

У цьому пості ми розглянемо поширені методи аутентифікації API в Laravel та процедуру документування їх за допомогою Scramble — сучасного інструмента для документації API у Laravel.

Специфікація OpenAPI підтримує кілька методів аутентифікації API. З недавнім оновленням Scramble тепер повністю підтримує специфікацію безпеки OpenAPI 3.1.0, що дозволяє документувати будь-який метод аутентифікації, доступний у специфікації.

# Аутентифікація Sanctum

Sanctum — це перевірений метод аутентифікації, який, напевно, обрали й ви!

Для безстанної аутентифікації Sanctum дозволяє надсилати токен аутентифікації в заголовку Authorization:

Authorization: Bearer ***

З Scramble ви можете задокументувати цю аутентифікацію, додавши наступний код до методу boot будь-якого сервіс-провайдера:

use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Support\Generator\OpenApi;
use Dedoc\Scramble\Support\Generator\SecurityScheme;

public function boot()
{
    Scramble::configure()
        ->withDocumentTransformers(function (OpenApi $openApi) {
            $openApi->secure(
                SecurityScheme::http('bearer')
            );
        });
}

Це встановлює стандартну схему безпеки для всіх ендпоінтів.

Якщо ви використовуєте станну аутентифікацію Sanctum та маршрути документації Scramble правильно налаштовані, ваша сесія аутентифікації працюватиме автоматично в режимі "Спробуйте це".

# Аутентифікація Passport

Для аутентифікації OAuth2 OpenAPI пропонує схему безпеки oauth2.

Scramble дозволяє точно визначити, як працює oauth2:

use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Support\Generator\OpenApi;
use Dedoc\Scramble\Support\Generator\SecurityScheme;
use Dedoc\Scramble\Support\Generator\SecuritySchemes\OAuthFlow;

public function boot()
{
    Scramble::configure()
        ->withDocumentTransformers(function (OpenApi $openApi) {
            $openApi->secure(
                SecurityScheme::oauth2()
                    ->flow('authorizationCode', function (OAuthFlow $flow) {
                        $flow
                            ->authorizationUrl(config('app.url').'/oauth/authorize')
                            ->tokenUrl(config('app.url').'/oauth/token')
                            ->addScope('*', 'все');
                    })
            );
        });
}

Ви можете визначити всі області, як показано тут, або вказати гранульовані області для вашого застосунку.

У той час як інтерфейс Stoplight Elements (за замовчуванням у Scramble) відображає вимогу oauth2, інші інтерфейси (Scalar, Swagger) також дозволяють користувачам отримувати токени API безпосередньо з документації.

# Документування ендпоінта Sanctum's oauth/token

Ви можете задокументувати ендпоінт oauth/token Sanctum за допомогою Scramble. Ось розширення, створене спільнотою, яке допомагає в цьому: https://gist.github.com/tech-codivores/ddce2b10a64f06fe0b1bcd4868c17039

Перед використанням розширення переконайтеся, що воно включене в документовані маршрути Scramble:

Scramble::configure()
    ->routes(function (Route $r) {
        return Str::startsWith($r->uri, 'api/')
            || $r->uri === 'oauth/token';
    })

# Користувацька аутентифікація

# Аутентифікація з кількома заголовками

Якщо ваша аутентифікація вимагає кількох заголовків, ви можете вказати їх у вимозі безпеки API:

use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Support\Generator\OpenApi;
use Dedoc\Scramble\Support\Generator\SecurityScheme;

public function boot()
{
    Scramble::configure()
        ->withDocumentTransformers(function (OpenApi $openApi) {
            $openApi->components->securitySchemes['tenant'] = SecurityScheme::apiKey('header', 'X-Tenant');
            $openApi->components->securitySchemes['bearer'] = SecurityScheme::http('bearer');

            $openApi->security[] = new SecurityRequirement([
                'tenant' => [],
                'bearer' => [],
            ]);
        });
}

В цьому випадку аутентифікація вимагає як заголовок X-Tenant, так і Authorization.

# Токен API в параметрах запиту

Якщо ваш токен API передається як параметр запиту, ви можете задокументувати це за допомогою наступного фрагмента:

use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Support\Generator\OpenApi;
use Dedoc\Scramble\Support\Generator\SecurityScheme;

public function boot()
{
    Scramble::configure()
        ->withDocumentTransformers(function (OpenApi $openApi) {
            $openApi->secure(
                SecurityScheme::apiKey('query', 'api_token')
            );
        });
}

Дізнатися більше про доступні схеми безпеки ви можете в документації Scramble: https://scramble.dedoc.co/usage/authentication.

# Виключення маршрутів з вимог аутентифікації

Щоб виключити конкретний маршрут з аутентифікації, використовуйте PHPDoc анотацію @unauthenticated:

/**
 * @unauthenticated
 */
public function index(Request $request)
{
    return response()->json(/* деякі дані */);
}

Проте трансформери операцій пропонують більше гнучкості.

Наприклад, щоб видалити вимоги аутентифікації з маршрутів без middleware auth::

public function boot()
{
    Scramble::configure()
        ->withOperationTransformers(function (Operation $operation, RouteInfo $routeInfo) {
            $routeMiddleware = $routeInfo->route->gatherMiddleware();

            $hasAuthMiddleware = collect($routeMiddleware)->contains(
                fn ($m) => Str::startsWith($m, 'auth:')
            );

            if (!$hasAuthMiddleware) {
                $operation->security = [];
            }
        });
}

Це автоматично позначає маршрути без middleware аутентифікації як публічні. Використовуючи цей підхід, ви також можете призначити специфічні вимоги безпеки операції.

# Висновок

Існує безліч способів реалізації аутентифікації API, і OpenAPI охоплює більшість з них.

З Scramble ви можете задокументувати налаштування аутентифікації вашого API та навіть автоматизувати вимоги аутентифікації, засновані на middleware, уникаючи ручних анотацій.

Якщо ви ще не пробували Scramble, обов'язково спробуйте! https://scramble.dedoc.co