В этой статье я хочу поделиться своей библиотекой, которая позволяет автоматически генерировать документацию OpenAPI для проектов на Lumen.

Проблема

Lumen — это легковесный PHP-фреймворк, который идеально подходит для создания микросервисов и API. Однако, одной из проблем при работе с Lumen является отсутствие встроенной поддержки для генерации документации OpenAPI. Это может привести к тому, что разработчикам приходится вручную создавать документацию, что может быть трудоёмким и подверженным ошибкам процессом.

Решение

Я разработал библиотеку, которая решает эту проблему. Библиотека называется openapi-generator-lumen и доступна на Packagist. Она позволяет автоматически генерировать документацию OpenAPI только на основе кода используя модуль PHP Reflection.

Как работает библиотека

Библиотека не использует аннотации или атрибуты в коде, используется модуль PHP Reflection для определения параметров запросов и ответов. Затем она генерирует документацию OpenAPI в формате JSON. Документация может быть использована для создания интерактивных интерфейсов для тестирования API, а также для генерации клиентских библиотек на различных языках программирования.

Вот как можно использовать библиотеку:

  1. Установите библиотеку через Composer:

composer require uraankhayayaal/openapi-generator-lumen

  1. Зарегистрируйте сервис-провайдер в bootstrap/app.php:

$app->register(Uraankhayayaal\OpenapiGeneratorLumen\Providers\OpenApiGeneratorProvider::class);

  1. Добавьте команду генератора OpenAPI в файл app/Console/Kernel.php:

protected $commands = [
    \Uraankhayayaal\OpenapiGeneratorLumen\Console\Commands\OpenApiGeneratorCommand::class,
];

  1. Определите параметры запросов и ответов в вашем коде. Для этого используйте классы, которые наследуются от Uraankhayayaal\OpenapiGeneratorLumen\Http\Requests\BaseRequestQueryData, Uraankhayayaal\OpenapiGeneratorLumen\Http\Requests\BaseRequestBodyDataи Illuminate\Http\Resources\Json\JsonResource.

  2. Сгенерируйте документацию с помощью команды:

php artisan openapi:generate

  1. Настройте конфигурацию генератора в файле config/openapi-generator.php. Здесь вы можете указать название, версию, серверы и другие параметры документации.

  2. Запустите генератор, и он создаст документацию в указанном вами месте.

Преимущества библиотеки

  • Автоматизация. Библиотека автоматически генерирует документацию на основе типизированных методов контроллера в коде, что избавляет разработчиков от необходимости создавать документацию вручную.

  • Точность. Поскольку документация генерируется на основе кода, она всегда актуальна и соответствует реальному поведению API.

  • Гибкость. Библиотека позволяет настраивать параметры документации, такие как название, версия, серверы и т.д.

Надеюсь, эта библиотека будет полезна для разработчиков, работающих с Lumen. Вы можете найти её на Packagist по адресу https://packagist.org/packages/uraankhayayaal/openapi-generator-lumen.