ewk/laravel-openapi

Reusable OpenAPI response envelopes, request bodies, parameters, and components for Laravel APIs.

0.1.0 2026-07-11 01:09 UTC

Requires

• php: >=8.3
• zircote/swagger-php: ^5.1 || ^6.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.75
• pestphp/pest: ^3.8 || ^4.0
• pestphp/pest-plugin-arch: ^3.1 || ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^11.5 || ^12.0
• rector/rector: ^2.1
• tomasvotruba/type-coverage: ^2.2

MIT

• Dimitrienko Vadim

• laravel
• swagger
• openapi
• Swagger-PHP
• api-documentation

Published on Packagist.org on 2026-07-11 01:12 UTC

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

Требования

Компонент	Поддержка
PHP	8.3+
zircote/swagger-php	5 / 6
Laravel	Не требуется

Возможности

• Обёртки ответов: один ресурс, коллекция, пагинация, сообщение и ответ без тела.
• Стандартные ошибки: готовые ответы для распространённых 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.

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

Раздел	Описание
Начало работы	Установка и первая генерация
Ответы	Успешные ответы и ошибки
Тела запросов	JSON, multipart и form-urlencoded
Параметры	Параметры query/path и их настройка
Архитектура	Конвейер, компоненты и расширение
AI Skills	Поставляемые skills и команда установки
Участие в разработке	Тесты и проверки качества

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

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

Лицензия

MIT