Як задокументувати кілька API в Laravel за допомогою Scramble

Одна програма на Laravel може містити кілька API. Це корисно для:

• Різних версій API
• Публічних та внутрішніх API
• API для фронтенд- та бекенд-використання

За допомогою Scramble ви можете створювати окрему документацію для кожного API.

За замовчуванням Scramble реєструє API з назвою "default" і включає всі кінцеві точки, де URI починається з api/.

Щоб додати нові API, просто зареєструйте їх, налаштуйте та надайте документацію.

# Приклад: документування кількох версій API

Розгляньте програму з двома версіями API:

// routes/api.php
Route::prefix('v1')->group(function () {
    // маршрути v1
});
 
Route::prefix('v2')->group(function () {
    // маршрути v2
});

Спочатку ми налаштуємо документацію API за замовчуванням для версії 1 (v1), змінивши конфігурацію, щоб використовувати api/v1 як префікс шляху:

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

Версію 2 (v2) потрібно підтвердити вручну. Це робиться шляхом виклику registerApi у методі boot сервісного постачальника, де слід вказати конкретні налаштування для v2. Першим параметром є назва API (яка може бути будь-яким рядком), а другим — налаштування Scramble, які застосовуються зверху стандартної конфігурації (config/scramble.php).

У нашому випадку зареєстрований API під назвою v2 (ми самі обираємо цю назву; це може бути internal, public тощо) використовуватиме стандартні налаштування, крім api_path, яке буде специфічно встановлено для v2:

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

Крім того, потрібно зареєструвати маршрути документації для v2. Це робиться шляхом виклику registerUiRoute та registerJsonSpecificationRoute, де першим параметром буде шлях документації, а другим — назва API (така, як використовувалася в registerApi):

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

Тепер ми маємо документацію, доступну для обох API:

# Документація v1:

• GET docs/api - Інтерфейс для перегляду документації v1
• GET docs/api.json - Документ OpenAPI 3.1.0 для v1

# Документація v2:

• GET docs/v2 - Інтерфейс для перегляду документації v2
• GET docs/v2/api.json - Документ OpenAPI 3.1.0 для v2

# Контроль доступу до документації

Якщо деякі версії API повинні бути публічними, а інші — приватними, можна налаштувати проміжне програмне забезпечення для їхніх маршрутів документації. Це особливо корисно для роботи з публічними та внутрішніми API.

За замовчуванням маршрути документації доступні лише в непрацівних середовищах. Ця логіка реалізована через проміжне програмне забезпечення RestrictedDocsAccess. Якщо ви хочете, щоб v1 був публічним, а v2 обмеженим для непрацівних середовищ, потрібно видалити RestrictedDocsAccess з v1 і додати його до v2.

# Робимо v1 публічним

Видаліть RestrictedDocsAccess з конфігурації за замовчуванням:

// config/scramble.php
...
'middleware' => [
    'web',
-   RestrictedDocsAccess::class,
],
...

# Обмеження v2

Явно активуйте RestrictedDocsAccess для v2:

// app/Providers/AppServiceProvider.php
use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;
 
public function boot()
{
    Scramble::registerApi('v2', [
        'api_path' => 'api/v2',
+       'middleware' => [
+           'web',
+           RestrictedDocsAccess::class,
+       ],
    ]);
}

Тепер документація v1 буде доступною публічно в продуктивному середовищі, в той час як v2 залишиться обмеженою для непрацівних середовищ.

# Кастомізація маршрутів документації v1

Ви також можете змінити маршрути документації за замовчуванням (GET docs/api, GET docs/api.json). Для цього потрібно відключити реєстрацію маршрутів за замовчуванням у методі register сервісного постачальника:

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

Потім вручну зареєструйте маршрути для API за замовчуванням:

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

# Висновок

Використовуючи Scramble, ви можете документувати кілька API в одній програмі на Laravel — для різних версій, публічного чи внутрішнього доступу, або відповідно до потреб різних клієнтів. Ви маєте повний контроль над маршрутами, проміжним програмним забезпеченням та іншими налаштуваннями для кожного API.

Спробуйте Scramble, якщо ще цього не зробили: https://scramble.dedoc.co