docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/sdk/client/generation.md
новий файл +93
−0
1
+
# Генерація SDK
2
+
3
+
SDK генерується з документа [OpenRPC](https://spec.open-rpc.org/) сервера. У JsonRpcBundle це відповідь `GET /rpc` (для інших версій — `GET /rpc/v2` тощо).
4
+
5
+
:::info
6
+
У Symfony-застосунку генеруйте через [SDK Bundle](/docs/api/sdk/bundle/commands): `bin/console ufo:sdk:generate`. Нижче — генерація самою бібліотекою.
7
+
:::
8
+
9
+
## Скрипт `bin/make.php`
10
+
11
+
```bash
12
+
php vendor/ufo-tech/json-rpc-client-sdk/bin/make.php https://api.example.com/rpc
13
+
```
14
+
15
+
Скрипт інтерактивний і запитує:
16
+
17
+
1. `Enter API vendor name:` — назва постачальника API; стане частиною простору імен (порожньо — `SDK`).
18
+
2. `Enter methods to ignore (comma separated):` — маски (див. «Фільтр методів» нижче) методів, які не треба генерувати.
19
+
20
+
Аргумент — URL документації. Без нього скрипт читає `bin/schema.json` поруч зі скриптом. Документацію запитує простим `GET` без заголовків, тож захищену `protected_doc` документацію так не отримати — використайте [SDK Bundle](/docs/api/sdk/bundle) або `HttpReader` з заголовками в коді.
21
+
22
+
Скрипт генерує класи в простір імен `Ufo\RpcSdk\Client\<Vendor>` — опцій для іншого простору імен немає. Для власного простору імен використовуйте генератор з коду (нижче) або SDK Bundle.
23
+
24
+
## Генерація з коду
25
+
26
+
```php
27
+
use Ufo\RpcSdk\Maker\Definitions\Configs\ConfigsHolder;
28
+
use Ufo\RpcSdk\Maker\DocReader\HttpReader;
29
+
30
+
$configs = new ConfigsHolder(
31
+
docReader: new HttpReader('https://api.example.com/rpc', ['Ufo-RPC-Token' => $token]),
32
+
projectRootDir: __DIR__,
33
+
apiVendorAlias: 'Orders',
34
+
namespace: 'App\Sdk',
35
+
cacheLifeTimeSecond: 3600,
36
+
ignoredMethods: ['Admin.*'],
37
+
);
38
+
```
39
+
40
+
Далі `Ufo\RpcSdk\Maker\Maker` з генераторами `SdkEnumMaker`, `SdkDtoMaker`, `SdkProcedureMaker`, `SdkConfigMaker` (так робить `bin/make.php` і SDK Bundle). Файли пишуться в каталог, на який у `composer.json` зіставлено простір імен (PSR-4), тож простір імен має бути зареєстрований в автозавантаженні.
41
+
42
+
Документ OpenRPC кешується в `var/cache/maker/` на `cacheLifeTimeSecond` секунд; після змін на сервері очистьте кеш або зменште час.
43
+
44
+
## Що читається з документації
45
+
46
+
* Підтримувані версії OpenRPC: 1.2.6, 1.3.0, 1.3.1, 1.3.2.
47
+
* Адреса сервера — `servers[0].url`; асинхронні транспорти — `servers[0].x-ufo.transport` (сервер JsonRpcBundle публікує їх при `docs.async_dsn_info: true`).
48
+
* Методи (`methods`), схеми DTO і enum (`components.schemas`), обмеження валідації (`x-ufo-assertions`).
49
+
* Метод `ping` не генерується — він є в кожному класі.
50
+
51
+
## Що генерується
52
+
53
+
Для постачальника `Orders` і простору імен `App\Sdk`:
54
+
55
+
| Що | Де | Приклад |
56
+
| --- | --- | --- |
57
+
| Класи процедур | `App\Sdk\Orders\` | метод `User.get` → клас `UserSDK`, метод `get()` |
58
+
| Асинхронні класи | `App\Sdk\Orders\` | `AsyncUserSDK` — лише якщо сервер публікує транспорт, назва якого починається з `rpc_async` |
59
+
| DTO | `App\Sdk\Orders\DTO\` | `UserDto` |
60
+
| Enum | `App\Sdk\Orders\Enums\` | `OrderStatus` з `values()`, `fromValue()`, `tryFromValue()` |
61
+
| Адреси серверів | `sdk_config.yaml.dist` у корені простору імен | див. нижче |
62
+
63
+
* Назва методу без роздільника потрапляє в клас `MainSDK`; назви методів переводяться в lowerCamelCase (`types_list` → `typesList`).
64
+
* Кожен метод має атрибут `#[ApiMethod('User.get')]`, параметри — `#[RPC\Assertions]` з обмеженнями сервера, застарілі методи — `#[Deprecated]`.
65
+
* Класи позначено тегами `ufo.sdk_method_class` / `ufo.async_sdk_method_class` — за ними SDK Bundle налаштовує сервіси.
66
+
* Повторна генерація видаляє й переписує файли класів — не редагуйте їх вручну.
67
+
68
+
### `sdk_config.yaml.dist`
69
+
70
+
```yaml
71
+
Orders:
72
+
sync: 'https://api.example.com/rpc'
73
+
rpc_async: 'amqp://{rpc_async_secret}@rabbit.example.com:5672/vhost/rpc'
74
+
```
75
+
76
+
Логін і пароль транспорту замінюються на плейсхолдер `{<назва транспорту>_secret}`; справжній секрет передається під час виконання. Записи інших постачальників у файлі зберігаються. Щоб змінити адреси для свого оточення, створіть поруч `sdk_config.yaml` — він має пріоритет над `.dist`.
77
+
78
+
## Фільтр методів
79
+
80
+
Маски задаються списком через кому (у `bin/make.php`) або масивом (`ignoredMethods`, `ignore_methods` у SDK Bundle). Порівняння без урахування регістру.
81
+
82
+
| Маска | Значення |
83
+
| --- | --- |
84
+
| `Admin.*` | Не генерувати методи, що підходять (`*` — будь-які символи) |
85
+
| `!Admin.ping` | Завжди генерувати, навіть якщо підходить під іншу маску |
86
+
| `~Report.*` | Генерувати лише асинхронну версію |
87
+
| `&Cart.*` | Генерувати лише синхронну версію |
88
+
89
+
Префікси `~` і `&` разом у масці — помилка генерації.
90
+
91
+
## Версії та групи API
92
+
93
+
Окремої підтримки [версій](/docs/api/json-rpc-bundle/functionality/versions) і [груп](/docs/api/json-rpc-bundle/functionality/groups) API в SDK немає. Генеруйте з адреси потрібної версії або групи (`/rpc/v2`, `/rpc/internal`) — сервер підставляє її в `servers[0].url`. Для кожної версії чи групи використовуйте окрему назву постачальника, інакше класи перезапишуть одне одного.