Comment documenter plusieurs API à Laravel avec Scramble

Les applications Laravel gèrent souvent plusieurs API, bénéfiques pour le versioning, la séparation d'un accès public et interne, ou répondant à différents besoins frontend / backend. Brouillé simplifie la documentation de ces diverses API.

La configuration par défaut de Scramble documente une API "par défaut", englobant les points de terminaison commençant par api/. L'ajout de plus d'API implique une exposition à l'enregistrement, à la configuration et à la documentation.

Exemple: documenter plusieurs versions API

Considérons une application avec deux versions API:

// routes/api.php
Route::prefix('v1')->group(function () {
    // v1 routes
});

Route::prefix('v2')->group(function () {
    // v2 routes
});

pour documenter v1, ajustez la configuration de brouillage:

// config/scramble.php
...
'api_path' => 'api/v1',
...

pour v2, enregistrez-le explicitement dans la méthode boot d'un fournisseur de services:

// app/Providers/AppServiceProvider.php
use Dedoc\Scramble\Facades\Scramble;

public function boot()
{
    Scramble::registerApi('v2', ['api_path' => 'api/v2']);
}

Enregistrez les routes de documentation v2 dans routes/web.php:

// routes/web.php
use Dedoc\Scramble\Facades\Scramble;

Scramble::registerUiRoute('docs/v2', api: 'v2');
Scramble::registerJsonSpecificationRoute('docs/v2/api.json', api: 'v2');

Maintenant, les deux API sont documentées:

• V1 Documentation:

  • GET docs/api: UI pour la documentation V1
  • GET docs/api.json: Spécification OpenAPI 3.1.0 pour v1

• V2 Documentation:

  • GET docs/v2: UI pour la documentation V2
  • GET docs/v2/api.json: Spécification OpenAPI 3.1.0 pour v2

Contrôle l'accès à la documentation

Pour les API publiques et privées, gérez le middleware. Par défaut, la documentation est limitée aux environnements de non-production via RestrictedDocsAccess middleware.

pour rendre v1 public, supprimez RestrictedDocsAccess de la configuration par défaut:

// config/scramble.php
...
'middleware' => [
    'web',
],
...

pour restreindre v2 à la non-production:

// app/Providers/AppServiceProvider.php
use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;

public function boot()
{
    Scramble::registerApi('v2', [
        'api_path' => 'api/v2',
        'middleware' => [
            'web',
            RestrictedDocsAccess::class,
        ],
    ]);
}

Maintenant, v1 est accessible au public en production, tandis que v2 reste limité à la non-production.

Personnalisation des routes de documentation V1

pour personnaliser les routes par défaut v1 (GET docs/api, GET docs/api.json), désactivez l'enregistrement par défaut de l'itinéraire:

// app/Providers/AppServiceProvider.php
public function register()
{
    Scramble::disableDefaultRoutes();
}

Ensuite, enregistrez-les manuellement:

// routes/web.php
Scramble::registerUiRoute('docs/v1', api: 'default');
Scramble::registerJsonSpecificationRoute('docs/v1/api.json', api: 'default');

Conclusion

Scramble gère efficacement la documentation de l'API multiple dans une seule application Laravel, offrant un contrôle granulaire sur les itinéraires, le middleware et la configuration pour chaque API. En savoir plus sur: 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!