PHPackages                             rollun-com/rollun-openapi - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. rollun-com/rollun-openapi

ActiveLibrary[API Development](/categories/api)

rollun-com/rollun-openapi
=========================

Bridge between rollun skeleton and openapi generated code

12.1.0(8mo ago)010.0k↓30%2[4 issues](https://github.com/rollun-lc/rollun-openapi/issues)[1 PRs](https://github.com/rollun-lc/rollun-openapi/pulls)MITPHPPHP >8.0CI passing

Since Sep 15Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/rollun-lc/rollun-openapi)[ Packagist](https://packagist.org/packages/rollun-com/rollun-openapi)[ RSS](/packages/rollun-com-rollun-openapi/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (26)Versions (111)Used By (0)

OpenAPI generator
=================

[](#openapi-generator)

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

> Openapi маніфест - це документ, з певною структурою, що описує HTTP API: url шляхи, формати даних запиту/відповіді, авторизацію і т.п. Детальніше можна почитати [тут](https://swagger.io/docs/specification/about/).
>
> На основі цього маніфесту можна згенерувати код для клієнтської або серверної частини.
>
> Для клієнтської частини генерується API клієнт, за допомогою якого можна відправляти запити до данного Api.
>
> Згенерованний код для серверної частини буде містити шаблон контролера, який потрібно імплементувати.
>
> І клієнт і сервер будуть містити валідацію та серіалізацію/десериалізацію даних з/в об'єкти для http запиту та відповіді.

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

Quick start
-----------

[](#quick-start)

### Що таке openapi

[](#що-таке-openapi)

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

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

```
openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
```

Детальніше про формат openapi документу можна почитати в [swagger.io документації](https://swagger.io/docs/specification/about/)

### Openapi generator

[](#openapi-generator-1)

Цей файл може використовуватись різними інструментами, наприклад, swagger ui генерує інтерфейс с [інтерактивною документацією](https://petstore.swagger.io/).

[![Swagger ui](docs/img/swagger-ui.png)](docs/img/swagger-ui.png)

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

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

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

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

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

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

[](#написання-маніфесту)

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

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

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

[![Swagger editor open manifests button](docs/img/swagger-editor-open-manifests.png)](docs/img/swagger-editor-open-manifests.png)

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

[![Swagger editor choosing skeleton manifests](docs/img/swagger-editor-choosing-skeleton.png)](docs/img/swagger-editor-choosing-skeleton.png)

Детальніше про правила створення маніфеста можна почитати в [manifests.md](docs/manifest.md)

> У гілці [`specification`](https://github.com/rollun-lc/rollun-openapi/blob/specification/docs/specification.md) є розписані (але ще не завершені) специфікації OpenAPI для різних сервісів.

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

[](#запуск-генератора)

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

`composer require rollun-com/rollun-openapi`

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

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

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

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

1. Встановити [openapi-generator v7](https://openapi-generator.tech/) собі у систему локально, за інструкцією на їх сайті.
2. Використовувати docker, та запускати цей скрипт всередині докер контейнеру.

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

[](#зуапуск-генерації-через-докер)

```
docker compose run --rm php-fpm php bin/openapi-generator generate:client
```

P.S В [образі php-fpm](./docker/php-fpm/8.1/Dockerfile) встановлено openapi-generator. ЦЕ ОБОВ'ЯЗКОВА УМОВА.

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

```
services:
  # ...

  php-openapi-generator:
    image: maxrollundev/php-openapi-generator:8.0
    volumes:
      - ./:/var/www/app
```

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

```
docker-compose run --rm php-openapi-generator \
  php vendor/bin/openapi-generator generate:server \
  -m openapi.yaml
```

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

[](#запуск-генерації-без-докеру)

1. Установите [openapi-generator](https://openapi-generator.tech/) (протестировано на версии 7.9.0). Для проверки выполните команду:

    `openapi-generator version`, в случае когда openapi-generator установлен вы увидите версию генератора.
2. Для генерации кода выполните команду:

    `php vendor/bin/openapi-generator generate:server`или `php vendor/bin/openapi-generator generate:client`

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

    `php vendor/bin/openapi-generator generate:client --manifest=openapy.yaml`

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

[](#налаштування-після-генерації)

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

```
"autoload": {
  "psr-4": {
    "SomeModule\\": "src/SomeModule/src/"
  }
},

```

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

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

[](#якщо-виникли-помилки)

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

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

    Рекомендованный способ это установить библиотеку rollun-com/rollun-logger. В комплекте с которой идет LifeCycleToken. Почитать о том как установить его в контейнер можно в [документации](https://github.com/rollun-com/rollun-logger/blob/master/docs/index.md#lifecycletoken)библиотеки.

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

[](#використання-згенерованого-сервера)

Серверний генератор генерує шаблони контролерів, які потрібно реалізувати програмістові. Шаблони контролера знаходиться за шляхом `src/{ManifestTitle}/src/OpenaAPI/{ManifestVersion}/Server/Rest`. Наприклад [User.php](src/HelloUser/src/OpenAPI/V1/Server/Rest/User.php) маніфесту [openapi.yaml](openapi.yaml)

```