docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/sdk/bundle/config.md
новий файл +50
−0
1
+
# Налаштування SDK Bundle
2
+
3
+
Файл `config/packages/json_rpc_sdk.yaml`, кореневий ключ `json_rpc_sdk`.
4
+
5
+
```yaml
6
+
json_rpc_sdk:
7
+
namespace: App\Sdk # корінь простору імен згенерованих класів
8
+
generate_url_in_attr: false
9
+
cache:
10
+
ttl: 3600 # кеш документації під час генерації, секунди
11
+
vendors:
12
+
- name: Orders
13
+
url: 'https://orders.example.com/rpc'
14
+
token_key: 'Ufo-RPC-Token'
15
+
token: '%env(resolve:ORDERS_API_TOKEN)%'
16
+
async_secret: '%env(resolve:ORDERS_ASYNC_SECRET)%'
17
+
ignore_methods: ['Admin.*', '~Report.*']
18
+
- name: Billing
19
+
url: '%kernel.project_dir%/docs/billing-openrpc.json'
20
+
```
21
+
22
+
| Параметр | За замовчуванням | Опис |
23
+
| --- | --- | --- |
24
+
| `namespace` | `App\Sdk` | Простір імен; класи постачальника — у `<namespace>\<Name>` (назва в CamelCase) |
25
+
| `generate_url_in_attr` | `false` | Записувати адресу сервера в атрибут класу (зараз не діє — див. [Актуальні помилки](/docs/api/sdk/client/known_issues/open)) |
26
+
| `cache.ttl` | `3600` | Скільки зберігати документацію сервера в `cache.app` під час генерації |
27
+
| `vendors[].name` | — (обов'язковий) | Назва постачальника: частина простору імен і ключ у `sdk_config.yaml` |
28
+
| `vendors[].url` | — (обов'язковий) | Адреса документації OpenRPC (`https://…/rpc`) або шлях до локального JSON-файлу |
29
+
| `vendors[].token_key` | — | Назва заголовка з токеном (як `security.token_name` сервера) |
30
+
| `vendors[].token` | — | Токен |
31
+
| `vendors[].async_secret` | — | `user:password` асинхронного транспорту; підставляється в DSN замість `{rpc_async_secret}` |
32
+
| `vendors[].ignore_methods` | `[]` | [Маски методів](/docs/api/sdk/client/generation), які не генерувати чи генерувати лише sync/async |
33
+
34
+
## Як використовуються токени
35
+
36
+
* Під час **генерації** `token_key` і `token` надсилаються в заголовку запиту документації, тож працює й захищена `protected_doc` документація.
37
+
* Під час **виклику** синхронні класи отримують заголовок `[token_key => token]`, асинхронні — `token` (у повідомленні черги) і `async_secret`.
38
+
* Токен підставляється лише тоді, коли задано **обидва** параметри `token_key` і `token`.
39
+
40
+
:::danger
41
+
Зберігайте токени й секрети у змінних оточення (`.env.local`, секрети Symfony), а не в YAML-файлі в репозиторії.
42
+
:::
43
+
44
+
## Кілька серверів
45
+
46
+
Кожен елемент `vendors` — окремий сервер з власним простором імен (`App\Sdk\Orders`, `App\Sdk\Billing`), токеном і записом у `sdk_config.yaml`. Для різних [версій](/docs/api/json-rpc-bundle/functionality/versions) чи [груп](/docs/api/json-rpc-bundle/functionality/groups) API одного сервера створюйте окремих постачальників з відповідними адресами (`/rpc/v2`, `/rpc/internal`).
47
+
48
+
## Адреси під час виконання
49
+
50
+
Адреса, на яку надсилаються запити, береться не з `vendors[].url`, а з `sdk_config.yaml` / `sdk_config.yaml.dist`, що генерується поруч із класами (адреса з документації сервера). Щоб використовувати іншу адресу в оточенні, створіть `sdk_config.yaml` з потрібними значеннями — див. [Генерація](/docs/api/sdk/client/generation).