Mendokumentasikan Pengesahan API di Laravel dengan Perebutan

Tutorial ini menunjukkan kaedah pengesahan API Laravel biasa dan dokumentasi mereka menggunakan Scramble, alat dokumentasi API moden. Perebutan sepenuhnya menyokong spesifikasi keselamatan OpenAPI 3.1.0, membolehkan dokumentasi kaedah pengesahan komprehensif.

Pengesahan Sanctum

Sanctum, kaedah pengesahan Laravel yang popular, menyokong kedua -dua pengesahan tanpa statur dan negara. Untuk pengesahan tanpa stat, token pembawa dihantar dalam header Authorization: Authorization: Bearer ***. Dokumen perebutan ini menggunakan kaedah boot pembekal perkhidmatan:

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

Ini menetapkan skim keselamatan token pembawa lalai untuk semua titik akhir. Pengesahan Stateful, jika laluan dokumentasi Scramble dikonfigurasi dengan betul, akan berfungsi secara automatik dalam ciri "Cuba Keluar".

Pengesahan Pasport

Untuk pengesahan OAuth2, OpenAPI menggunakan skim keselamatan

. Perebutan membolehkan konfigurasi yang tepat: 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('*', 'all');
                    })
            );
        });
}

Skop boleh ditakrifkan secara global atau dengan kawalan berbutir. Walaupun Elemen Stoplight (UI lalai Scramble) memaparkan keperluan

, UIS lain (skalar, swagger) memudahkan pengambilalihan token langsung dari dokumentasi. oauth2

Mendokumentasikan Sanctum's endpoint

Mendokumentasikan titik akhir Sanctum's oauth/token boleh dicapai dengan sambungan perebutan yang dikontribusi oleh komuniti:

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

. Ingatlah untuk memasukkannya dalam laluan dokumentasi Scramble: oauth/token

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

Pengesahan Custom

Pengesahan Header Pelbagai

untuk pengesahan yang memerlukan pelbagai tajuk, tentukannya dalam keperluan keselamatan API:

ini mandat kedua -dua

dan

tajuk.

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

token API dalam parameter pertanyaan X-Tenant Authorization Jika token API adalah parameter pertanyaan, gunakan:

Rujuk dokumentasi Scramble untuk lebih banyak Skim Keselamatan Butiran:

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

.

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

tidak termasuk laluan dari pengesahan

anotasi phpDoc tidak termasuk laluan dari pengesahan. Transformer operasi memberikan lebih banyak fleksibiliti. Sebagai contoh, untuk mengecualikan laluan yang kurang

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

Ini secara automatik menunjuk laluan tanpa middleware pengesahan sebagai orang awam. Pendekatan ini juga membolehkan menetapkan keperluan keselamatan khusus untuk operasi.

Kesimpulan

OpenAPI dan Scramble menawarkan penyelesaian yang mantap untuk mendokumentasikan pelbagai kaedah pengesahan API, termasuk pengendalian automatik berdasarkan middleware, meminimumkan anotasi manual. Terokai perebutan di https://www.php.cn/link/0fcbc3c0cf262c771001930af2406bbc .

Atas ialah kandungan terperinci Mendokumentasikan Pengesahan API di Laravel dengan Perebutan. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!