Dokumentieren Sie die API -Authentifizierung in Laravel mit Scramble

Dieses Tutorial zeigt gemeinsame Methoden der Laravel -API -Authentifizierungsmethoden und deren Dokumentation unter Verwendung von Scramble, einem modernen API -Dokumentationstool. Scramble unterstützt OpenAPI 3.1.0 Sicherheitsspezifikationen und ermöglicht eine umfassende Dokumentation der Authentifizierungsmethode.

Sanctum -Authentifizierung

Sanctum, eine beliebte Laravel -Authentifizierungsmethode, unterstützt sowohl die staatenlose als auch die staatliche Authentifizierung. Für die staatenlose Authentifizierung wird ein Trägertoken in den Authorization -Header geschickt: Authorization: Bearer ***. Scramble dokumente dies mit der boot -Methode eines Dienstanbieters:

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

Dies legt ein Standard -Bearer -Token -Sicherheitsschema für alle Endpunkte fest. Statistische Authentifizierung, wenn die Dokumentationsrouten von Scramble korrekt konfiguriert sind, funktionieren automatisch in der Funktion "Try It Out".

Pass -Authentifizierung

Für die OAuth2 -Authentifizierung verwendet OpenAPI das Sicherheitsschema oauth2. Scramble ermöglicht eine präzise Konfiguration:

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

Scopes können weltweit oder mit körniger Kontrolle definiert werden. Während die Stoplight -Elemente (Scramble Standard -Benutzeroberfläche) oauth2 Anforderungen anzeigen

Dokumentieren von Sanctums

Endpunkt oauth/token

Dokumentieren von Sanctums

Endpunkt ist mit einer von der Community kontributierten Scramble-Erweiterung erreichbar: oauth/token https://www.php.cn/link/e14c38bd11cd714b970735ade2f23fa . Denken Sie daran, es in die dokumentierbaren Routen von Scramble aufzunehmen:

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

benutzerdefinierte Authentifizierung

Multiple Header -Authentifizierung

für die Authentifizierung, die mehrere Header erfordert, geben Sie diese innerhalb der API -Sicherheitsanforderung an:

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

Dies meist sowohl

als auch X-Tenant Header. Authorization

API -Token in Abfrageparametern

Wenn das API -Token ein Abfrageparameter ist, verwenden Sie:

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

Weitere Informationen zum Sicherheitsschema finden Sie in der Dokumentation von Scramble:

https://www.php.cn/link/2a174f994bb16b9b11e6ea5c00a671c5 .

Ausschluss von Routen aus der Authentifizierung

Die Annotation

phpdoc schließt Routen aus der Authentifizierung aus. Betriebstransformatoren bieten mehr Flexibilität. Zum Beispiel, um Routen zu befreit, ohne @unauthenticated Middleware: auth:

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

Dadurch wird automatisch Routen ohne Authentifizierung Middleware als öffentlich angegeben. Dieser Ansatz ermöglicht auch die Zuweisung spezifischer Sicherheitsanforderungen an den Betrieb.

Schlussfolgerung

OpenAPI und Scramble bieten robuste Lösungen für die Dokumentation verschiedener API -Authentifizierungsmethoden, einschließlich automatisierter Handhabung auf der Grundlage von Middleware, minimieren manuelle Anmerkungen. Explore Scramble unter https://www.php.cn/link/0fcbc3c0cf262c771001930af2406bbc .

Das obige ist der detaillierte Inhalt vonDokumentieren Sie die API -Authentifizierung in Laravel mit Scramble. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!