Laravel OpenAPI CLI генерує Artisan-команди з вашої OpenAPI-специфікації

Spatie випустила Laravel OpenAPI CLI — пакет, який перетворює специфікації OpenAPI на окремі Artisan-команди для Laravel. Кожен API endpoint у вашій специфікації отримує власну команду з типізованими опціями для path і query-параметрів та для тіл запитів.

# Як це працює

Після встановлення зареєструйте URL специфікації OpenAPI через фасад OpenApiCli — зазвичай у AppServiceProvider:

namespace App\Providers;
 
use Illuminate\Support\ServiceProvider;
use Spatie\OpenApiCli\Facades\OpenApiCli;
 
class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        OpenApiCli::register('https://api.acme.com/openapi.yaml', 'acme')
            ->baseUrl('https://api.acme.com')
            ->bearer(env('ACME_API_TOKEN'));
    }
}

Якщо специфікація визначає GET /orders, POST /orders і DELETE /orders/{order_id}, пакет згенерує такі Artisan-команди:

• acme:get-orders
• acme:post-orders
• acme:delete-orders
• acme:list

Команда acme:list відображає всі доступні endpoints і їхні описи.

Команди мають формат {prefix}:{http-method}-{path}, де prefix — ім'я, вказане при реєстрації (2-й параметр методу register), а шлях перетворюється в kebab-case з видаленими path-параметрами. Тому GET /orders/{order_id}/items стане acme:get-orders-items. Якщо у специфікації задані operation IDs, можна використовувати їх за допомогою ->useOperationIds().

# Запуск команд

Будь-яку згенеровану команду можна викликати прямо в терміналі:

php artisan acme:get-orders --limit=10

За замовчуванням відповіді виводяться у вигляді читабельних таблиць. Щоб отримати YAML, додайте прапорець --yaml:

php artisan acme:get-orders --limit=10 --yaml

# Path і query-параметри

Path-параметри — обов'язкові опції, query-параметри — необов'язкові. Обидва типи конвертуються в kebab-case — тож order_id і orderId обидва стають --order-id:

# Path parameter
php artisan acme:get-orders-items --order-id=42
 
# Multiple path parameters
php artisan acme:delete-customers-orders --customer-id=1 --order-id=7
 
# Query parameters
php artisan acme:get-orders --status=pending --limit=10

Нотація з дужками в query-параметрах також спрощується в kebab-case, тому filter[status] стає --filter-status.

# Надсилання даних

Для endpoint-ів, що приймають тіло запиту, можна передавати поля окремо за допомогою --field:

php artisan acme:post-orders --field customer_id=1 --field status="pending"

Поля за замовчуванням відправляються як JSON, якщо лише в специфікації не вказано application/x-www-form-urlencoded. Щоб передати сирий JSON, використовуйте --input:

php artisan acme:post-orders --input '{"customer_id":1,"shipping":{"address":"123 Main St","city":"New York"}}'

Зауважте, що --field і --input не можна комбінувати. Для завантаження файлів префіксуйте значення поля символом @:

php artisan acme:post-orders-attachments --order-id=67 --field file=@/path/to/invoice.pdf

Якщо будь-яке поле містить файл, запит надсилається як multipart/form-data.

# Параметри конфігурації

API реєстрації також підтримує кілька опцій через fluent-інтерфейс:

OpenApiCli::register('https://api.acme.com/openapi.yaml', 'acme')
    ->baseUrl('https://api.acme.com')
    ->bearer(env('ACME_API_TOKEN'))
    ->banner('Acme Orders API v2')
    ->cache(ttl: 600)
    ->followRedirects()
    ->yamlOutput()
    ->showHtmlBody()
    ->useOperationIds()
    ->onError(function (Response $response, Command $command) {
        return match ($response->status()) {
            429 => $command->warn('Rate limited...'),
            default => false,
        };
    });

Кілька ключових опцій:

• cache(ttl: 600) — кешує відповіді на вказану кількість секунд
• followRedirects() — автоматично слідує за HTTP-редиректами
• useOperationIds() — іменує команди за operation IDs зі специфікації замість HTTP-методу і шляху
• onError() — приймає callback для обробки конкретних HTTP-статусів помилок

# Встановлення

Встановіть через Composer:

composer require spatie/laravel-openapi-cli

Пакет також добре інтегрується з Laravel Zero — фреймворком для створення автономних CLI-застосунків.

Повна документація доступна на Spatie's docs site, а вихідний код можна переглянути на GitHub.