ScrambleでLaravelでAPI認証を文書化します

このチュートリアルでは、最新のAPIドキュメントツールであるScrambleを使用して、一般的なLaravel API認証方法とそのドキュメントを示しています。 スクランブルはOpenapi 3.1.0セキュリティ仕様を完全にサポートし、包括的な認証方法ドキュメントを有効にします。

Sanctum Authentication

Laravel認証方法である

Sanctumは、StatelessとStateful認証の両方をサポートしています。 ステートレス認証のために、ベアラートークンが

ヘッダーで送信されます：

。 Scrambleは、サービスプロバイダーのAuthorizationメソッド：Authorization: Bearer ***を使用してこれを文書化します 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')
            );
        });
}

これにより、すべてのエンドポイントにデフォルトのベアラートークンセキュリティスキームが設定されます。 Scrambleのドキュメントルートが正しく構成されている場合、Stateful認証は、「Try It Out」機能内で自動的に機能します。

パスポート認証

OAUTH2認証の場合、OpenAPIは

セキュリティスキームを利用します。 スクランブルを使用すると、正確な構成が可能になります：

oauth2スコープは、グローバルに、または粒状制御で定義できます。 Stoplight Elements（ScrambleのデフォルトのUI）が要件を表示しますが、その他のUI（Scalar、Swagger）がドキュメントからの直接トークンの取得を促進します。

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('*', 'all');
                    })
            );
        });
}

Sanctumのエンドポイントoauth2の文書化 Sanctumのドキュメントのドキュメントは、コミュニティが制定したスクランブルエクステンションで達成可能です：

https://www.php.cn/link/e14c38bd11cd714b970735ade2f233fa

oauth/token

カスタム認証

oauth/token複数のヘッダー認証 複数のヘッダーを必要とする認証については、APIセキュリティ要件内でそれらを指定します。

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

これは、

との両方のヘッダーの両方を義務付けています。

クエリパラメーターのAPIトークン

APIトークンがクエリパラメーターの場合は、

を使用します

より多くのセキュリティスキームの詳細については、Scrambleのドキュメントを参照してください。

認証からルートを除外

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' => [],
            ]);
        });
}

phpdocアノテーションは、認証からルートを除外します。 オペレーショントランスは、より柔軟性を提供します。 たとえば、ミドルウェアのないルートを免除するには：X-Tenant

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')
            );
        });
}

これにより、認証ミドルウェアなしでルートが公開されます。 このアプローチにより、特定のセキュリティ要件を運用に割り当てることもできます。

結論

OpenapiとScrambleは、ミドルウェアに基づいた自動処理、手動注釈の最小化など、さまざまなAPI認証方法を文書化するための堅牢なソリューションを提供します。 スクランブルを探索してください

https://www.php.cn/link/0fcbc3c0cf262c771001930af2406bbc。

以上がScrambleでLaravelでAPI認証を文書化しますの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。