Documenter l'authentification de l'API à Laravel avec Scramble

Ce tutoriel démontre des méthodes d'authentification API Laravel communes et leur documentation à l'aide de Scramble, un outil de documentation API moderne. Scramble prend en charge les spécifications de sécurité OpenAPI 3.1.0, permettant la documentation complète de la méthode d'authentification.

Authentification Sanctum

Sanctum, une méthode populaire d'authentification de Laravel, prend en charge l'authentification apatride et avec état. Pour l'authentification sans état, un jeton de porteur est envoyé dans l'en-tête Authorization: Authorization: Bearer ***. Souchée documente ceci à l'aide d'une méthode boot d'un fournisseur de services:

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

Cela définit un schéma de sécurité de jeton de porteur par défaut pour tous les points de terminaison. L'authentification avec état, si les routes de documentation de Scramble sont correctement configurées, fonctionnera automatiquement dans la fonctionnalité "Try It Out".

Authentification du passeport

Pour l'authentification OAuth2, OpenAPI utilise le schéma de sécurité oauth2. Scramble permet une configuration précise:

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

Les portées peuvent être définies à l'échelle mondiale ou avec un contrôle granulaire. Alors que les éléments de feu des stop (l'interface utilisateur par défaut de Scramble) affiche oauth2 exigences, les autres UIS (Scalar, Swagger) facilitent l'acquisition de jetons directs à partir de la documentation.

documenter le point de terminaison de Sanctum oauth/token

Documenter le point de terminaison de Sanctum oauth/token est réalisable avec une extension de brouillure contribuée à la communauté: https://www.php.cn/link/e14c38bd11cd714b970735ade2f233fa . N'oubliez pas de l'inclure dans les routes documentables de Scramble:

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

Authentification personnalisée

Authentification de l'en-tête multiple

Pour l'authentification nécessitant plusieurs en-têtes, spécifiez-les dans l'exigence de sécurité de l'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' => [],
            ]);
        });
}

Cela oblige les en-têtes X-Tenant et Authorization.

jeton API dans les paramètres de requête

Si le jeton API est un paramètre de requête, utilisez:

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

Reportez-vous à la documentation de Scramble pour plus de détails sur le schéma de sécurité: https://www.php.cn/link/2a174f994bb16b9b11e6ea5c00a671c5 .

excluant les routes de l'authentification

L'annotation PHPDOC @unauthenticated PHPDOC exclut les routes de l'authentification. Les transformateurs de l'opération offrent plus de flexibilité. Par exemple, pour exempter les routes manquant auth: middleware:

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

Cela désigne automatiquement les itinéraires sans middleware d'authentification en tant que public. Cette approche permet également d'attribuer des exigences de sécurité spécifiques aux opérations.

Conclusion

OpenAPI et Scramble proposent des solutions robustes pour documenter diverses méthodes d'authentification API, y compris la manipulation automatisée basée sur le middleware, la minimisation des annotations manuelles. Explorez la ruée vers https://www.php.cn/link/0fcbc3c0cf262c771001930af2406bbc .

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!