Download the PHP package rollun-com/rollun-openapi without Composer

On this page you can find all versions of the php package rollun-com/rollun-openapi. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package rollun-openapi

OpenAPI generator

Ця бібліотека містить php скрипт, що генерує код клієнтської або серверної сторони з openapi маніфесту. Скрипт працює за допомогою утиліти openapi-generator.

Openapi маніфест - це документ, з певною структурою, що описує HTTP API: url шляхи, формати даних запиту/відповіді, авторизацію і т.п. Детальніше можна почитати тут.

На основі цього маніфесту можна згенерувати код для клієнтської або серверної частини.

Для клієнтської частини генерується API клієнт, за допомогою якого можна відправляти запити до данного Api.

Згенерованний код для серверної частини буде містити шаблон контролера, який потрібно імплементувати.

І клієнт і сервер будуть містити валідацію та серіалізацію/десериалізацію даних з/в об'єкти для http запиту та відповіді.

Також цю бібліотеку потрібно підключати в require секцію composer.json свого проекту, оскільки вона містить класи, що потрібні для роботи згенерованого коду.

Quick start

Що таке openapi

Openapi - це формат файлу, який описує http API: формати запиту/відповіді та кінцеві точки.

Простий варіант openapi файлу, що описує api с однією кінцевою точкою /users, яка повертає массив імен користувачів, виглядає наступним чином:

Детальніше про формат openapi документу можна почитати в swagger.io документації

Openapi generator

Цей файл може використовуватись різними інструментами, наприклад, swagger ui генерує інтерфейс с інтерактивною документацією.

Існує також інструмент openapi-generator, що дозволяє генерувати код на основі openapi документу (маніфесту). Цей код може містити об'єкти запиту/відповіді, їх валідацію, дисеріалізацію та серіалізацію з/в різні медіа типи, тести та т.п.

Генератори коди можна поділити на два типи: серверні та клієнтські. Які використовуються відповідно до того чи ваша программа діє як клієнт чи сервер, чи обидва варіанти відразу (проксі сервер).

Серверні генератори генерують шаблони контроллерів, які программіст повинен імплементувати, щоб отримати валідний сервер на який можна відправляти запити.

Клієнтські генератори генерують код, що дозволяє зручно відправляти запити на сервер та оброблювати відповідь.

Фактично наш генератор складається з двох генераторів: клієнтського і серверного, які запускаються командами generate:client та generate:server відповідно.

Написання маніфесту

Зазвичай маніфест пишеться або тим хто реалізовує api або тим кому потрібно api.

Для написання маніфестів ми використовуємо розгорнутий на наших серверах swagger-editor, доступний за посиланням: swagger-editor.rollun.net. Цей редактор поєднанний з репозиторієм rollun-com/openapi-manifests на github, де зберігаються усі наші маніфести, та дозволяє відкривати або зберігати маніфести в цей репозиторій. Важливо зберігати маніфести в цей репозиторій, оскільки він може використовуватись нашими программами для пошуку маніфестів. Інструкція по зберіганню маніфестів знаходиться в репозиторії rollun-com/openapi-manifests

Для того, щоб спростити написання маніфестів у нас існує манфест шаблон, під назвою skeleton. Його можна знайти натиснувши кнопку open manifests в swagger-editor:

Після чого відкриється вікно вибору маніфесту, в якому можна знайти skeleton маніфест.

Детальніше про правила створення маніфеста можна почитати в manifests.md

Запуск генератора

Встановіть бібліотеку у свій проект(мікросервіс):

Важливо Після того, як композер відпрацює, перевірьте що у файлі /config/config.php присутній конфіг провайдер \OpenAPI\ConfigProvider::class, а також він завантажується після \Zend\Expressive\Router\FastRouteRouter\ConfigProvider::class або \Mezzio\Router\FastRouteRouter\ConfigProvider::class інакше не буде працювати.

Після цього вам через php потрібно запустити скрипт ./bin/openapi-generator даної бібліотеки з командою generate:server, якщо ви хочете згенерувати код для серверної частини, і, відповідно generate:client для клієнта. Шлях до маніфесту скрипт запитає сам, але також його можна відразу вказати через параметр -m.

Якщо ви встановили цю бібліотеку через composer у свій проект, то цей скрипт буде знаходитись за шляхом ./vendor/bin/openapi-generator, а не ./bin/openapi-generator

Важливо, щоб не отримати помилку, цей скрипт повинен запускатись в оточені, де встановлено утиліту openapi-generator. Це можна добитись двома шляхами:

  1. Встановити openapi-generator собі у систему локально, за інструкцією на їх сайті.
  2. Використовувати docker, та запускати цей скрипт всередині докер контейнеру.

Зуапуск генерації через докер

Де:

Якщо ви використовуєте docker-compose в проекті, то в розділ services можна додати сервіс генератора

та запускати генератор за допомогою

Запуск генерації без докеру

  1. Установите openapi-generator ниже 5й (не включительно). Для проверки выполните команду:

    , в случае когда openapi-generator установлен вы увидите версию генератора.

    ВЕРСИЯ ГЕНЕРАТОРА ДОЛЖНА БЫТЬ НИЖЕ ПЯТОЙ. Связанно это с тем что в 5й версии убрали генератор которым мы пользуемся, ему изменили имя и переделали для Laminas вместо Zend.

  2. Для генерации кода выполните команду:

    или

    Команда поддерживает параметры. Передаются в виде --name=value. На данный момент реализовано указание манифеста (параметр manifest) в виде пути или урла. Например

Налаштування після генерації

Обязательно добавьте сгенерированные классы в аутолоадер композера.

Де, SomeModule - це title маніфесту

Якщо виникли помилки

  1. Проверьте что в контейнере есть rollun\logger\LifeCycleToken.

    Под этим именем в контейнере должна находиться строка с идентификатором текущего жизненного цикла приложения.

    Рекомендованный способ это установить библиотеку rollun-com/rollun-logger. В комплекте с которой идет LifeCycleToken. Почитать о том как установить его в контейнер можно в документации библиотеки.

Використання згенерованого сервера

Серверний генератор генерує шаблони контролерів, які потрібно реалізувати програмістові. Шаблони контролера знаходиться за шляхом src/{ManifestTitle}/src/OpenaAPI/{ManifestVersion}/Server/Rest. Наприклад openapi.yaml

Саме методи post, getById цього класу будуть викликатись при обробці запитів. Як видно цей клас делегує ці методи деякому controllerObject. Цей controllerObject це клас який повинен створити програміст, в якому написати реалізацію усіх потрібних методів (post, getById в даному випадку). Приклад UserController. Після чого розмістити цей клас в dependency injection контейнері під ім'ям з константи CONTROLLER_OBJECT, в данному випадку 'User1Controller'. Це простіше всього зробити прописавши alias в конфігурації: приклад

Використання згенерованого клієнта

З клієнтом все простіше, від програміста не потрібно ніяких додаткових дій після генерації. Аналогічно серверу в директорію src/{ManifestTitle}/src/OpenaAPI/{ManifestVersion}/Client/Rest генеруються класи Api клієнтів, що дозволяють відправляти запити.

Потрібний клас можна дістати із контейнера і він вже готовий до використання.

Формат даты и времени

Формат даты и времени, согласно спецификации OpenApi должен возвращаться в формате RFC 3339, section 5.6. Примеры: "2017-07-21T17:32:28Z", "2020-12-11T15:04:02.255Z". Важно заметить, что php формат \DateTime::RFC3339 ('Y-m-d\TH:i:sP') не в полной степени соответствует настоящему RFC 3339 формату, а именно в php \DateTime::RFC3339 не допускается Z в конце строки, а так же нету поддержки необязательных миллисекунд.

До версии 6.1.0 миллисекунды не поддерживаются, валидация даты времени происходит за форматом 'Y-m-d\TH:i:s\Z'.

С версии 6.1.0 валидатор дописан для полного соответствия спецификации RFC 3339, section 5.6. Но, обязательно нужно перегенерировать код, чтобы поменялся формат даты в анотациях сгенерированных DTO.

Помещать ли библиотеку в require-dev секцию?

Нет, почти все классы с этой библиотеки нужны для работы в продакшене: роутинг, сереализация дто и т.д. Для генерации кода используются только команды из ./bin директории, шаблоны из template, а так же пакет . Пока что эти зависимости остаются в пакете и подтягиваются в продакшн.

Документация по реализации серверной части

Документация по реализации серверной части

Документация по реализации клиентской части

Документация по реализации клиентской части

Переключение между хостами

С версии 3.1.0 Rest классы реализуют интерфейс OpenAPI\Client\Rest\ClientInterface, который включает в себя интерфейс OpenAPI\Client\Rest\HostSelectionInterface, который позволяет переключаться между хостами.

Чтобы воспользоваться этой возможностью, замените OpenAPI\Server\Rest\RestInterface на OpenAPI\Client\Rest\ClientInterface, который так же включает в себя RestInterface, так что ничего не сломается.

Зависает composer install

Возможно проблема из-за библиотеки "rollun-com/rollun-callback". Попробуйте убрать ее из composer.json и запустить установку повторно. Если все прошло успешно, то установите эту библиотеку отдельно через composer require.

Пользовательские действия и эндпоинты

Добавилась возможность кроме стандартных операций (CRUD), генерировать код для отправки с клиента и обработки сервером пользовательских методов, которые будут работать по нужным вам эндпоинтам.

Ранее у нас была возможность генерировать лишь 8 методов и, соответственно, иметь лишь 8 путей, например для какой-то сущности "Order":

PHP method Http method Path Action
1 post POST /order Создание
2 patch PATCH /order Создание или замена
3 get GET /order Получение коллекции
4 delete DELETE /order Удаление коллекции(?)
5 idGet GET /order/{id} Получение сущности
6 idPatch PATCH /order/{id} Частичное обновление сущности
7 idPut PUT /order/{id} Замена сущности
8 idDelete DELETE /order/{id} Удаление сущности

Сейчас можно генерировать любые другие PHP методы с любыми другими путями. Например, нужно сгенерировать метод, который будет обрабатывать POST запрос по пути /order/{id}/user. Для этого, в первую очередь, необходимо добавить нужный путь в манифест. Далее есть 2 варианта, как привязать этот путь к вашему PHP методу.

Вариант 1. Вы можете ничего более (кроме пути) не указывать

В этом случае будет сгенерирован метод OrderIdUserPost. То есть методы в классах (Handler, Rest, Api) будут генерироваться автоматически по следующей схеме - путь + http метод (все в camelCase). В контроллере необходимо описать метод с таким же названием. Этот метод будет принимать 2 параметра - $id и $bodyData, то есть в контроллер должен выглядеть примерно так:

Вариант 2. Указать в манифесте operationId.

Если вы не хотите, чтобы методы генерировались таким образом, т.е. если методу нужно задать какое-то свое логически понятное имя, в манифесте можно указать operationId.

В этом случае все методы будут иметь название setOrderUser. Соответственно, в контроллере тоже нужно описать метод с таким же именем.

Замечание по поводу длины путей. Желательно чтобы пути были не больше двух уровней. То есть допускаются пути /order/{id}/user, но не допускаются /order/{id}/user/roles и т.п.

Запуск тестов

С помощью docker

Нужно чтобы в системе были установлены:

Достаточно сначала запустить make up чтобы запустить приложение. После чего для выполнения тестов make test. Чтобы остановить приложение запустите make down.

Без docker

Тесты можно запустить через composer test. Внутри некоторых тестов поднимается встроеный php сервер и слушает порт 8081, так что важно чтобы он был сводобен.

Common issues


All versions of rollun-openapi with dependencies

PHP Build Version
Package Version
Requires php Version >8.0
ext-curl Version *
ext-json Version *
ext-mbstring Version *
articus/data-transfer Version ^0.5.2
articus/path-handler Version 0.6.1
laminas/laminas-cache Version ^3.1.2
doctrine/annotations Version ^1.8
laminas/laminas-cache-storage-adapter-blackhole Version ^2.0.0
laminas/laminas-cache-storage-adapter-filesystem Version ^2.0.1
laminas/laminas-code Version *
laminas/laminas-component-installer Version *
laminas/laminas-config-aggregator Version ^1.7
laminas/laminas-diactoros Version ^2.8.0
laminas/laminas-serializer Version ^2.13.0
laminas/laminas-servicemanager Version ^3.10
mezzio/mezzio Version ^3.9
mezzio/mezzio-fastroute Version ^3.4
mezzio/mezzio-helpers Version ^5.8
nette/php-generator Version ^3.4
nikic/fast-route Version ^1.3
rollun-com/rollun-callback Version ^7.0.0
rollun-com/rollun-dic Version ^4.0.0
symfony/dotenv Version ^6.0.3
guzzle/guzzle Version dev-php-8.0 as v3.9.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package rollun-com/rollun-openapi contains the following files

Loading the files please wait ....