README

Переиспользуемые обёртки ответов, тела запросов и параметры OpenAPI для проектов на swagger-php.

ewk/laravel-openapi сокращает повторение атрибутов OpenAPI: операция сохраняет собственное описание ответа, а общая структура данных регистрируется в components.schemas или components.parameters. Laravel runtime для работы пакета не требуется.

Быстрый старт

composer require ewk/laravel-openapi

Подключите процессор пакета к автономному генератору:

<?php

declare(strict_types=1);

use Ewk\LaravelOpenApi\Processors\ProcessorPipeline;
use OpenApi\Generator;

$generator = ProcessorPipeline::configure(new Generator());
$openApi = $generator->generate([__DIR__ . '/app']);

Требования

Возможности

• Обёртки ответов: один ресурс, коллекция, пагинация, сообщение и ответ без тела.
• Стандартные ошибки: готовые ответы для распространённых HTTP-кодов.
• Тела запросов: JSON, multipart и form-urlencoded со схемой приложения.
• Переиспользуемые параметры: страница, лимит, поиск, сортировка, локаль и идентификатор.
• Безопасные компоненты: автоматическое именование, дедупликация и явные конфликты.
• AI skills: инструкции для настройки, ответов, тел запросов и расширения компонентов.
• Независимость от Laravel: единственная runtime-зависимость - swagger-php.

Пример

Укажите класс, на котором объявлена OA\Schema. Пакет зарегистрирует переиспользуемую обёртку и заменит ответ операции ссылкой на неё.

<?php

declare(strict_types=1);

use App\OpenApi\Schemas\UserSchema;
use Ewk\LaravelOpenApi\Parameters\IdOrSlugParameter;
use Ewk\LaravelOpenApi\Responses\DataResponse;
use Ewk\LaravelOpenApi\Responses\NotFoundResponse;
use OpenApi\Attributes as OA;

final class UserController
{
    #[OA\Get(
        path: '/users/{idOrSlug}',
        parameters: [new IdOrSlugParameter()],
        responses: [
            new DataResponse(schema: UserSchema::class, description: 'User details'),
            new NotFoundResponse(),
        ],
    )]
    public function show(): void {}
}

В итоговом документе ответ 200 ссылается на #/components/schemas/UserResponse, а его data - на схему приложения User.

Документация

Границы пакета

Пакет не генерирует схемы приложения из Laravel models/resources, не содержит service provider и не заменяет сканер OpenAPI. Он добавляет готовые атрибуты и процессор к существующему процессу генерации swagger-php.

Лицензия

MIT