docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/rest-bundle/developers/known_issues/open.md
новий файл +21
−0
1
+
# Актуальні помилки
2
+
3
+
Відомі помилки й обмеження поточної версії REST Bundle (1.3, ще не випущена; останній реліз — 1.2.0): симптом, причина та обхідний шлях. Виправлені — на сторінці [Виправлені помилки](/docs/api/rest-bundle/developers/known_issues/fixed).
4
+
5
+
<include>(.issues/core-validation-400.md)
6
+
7
+
---
8
+
9
+
<include>(.issues/enum-not-cast.md)
10
+
11
+
---
12
+
13
+
<include>(.issues/get-params-as-body.md)
14
+
15
+
---
16
+
17
+
<include>(.issues/single-http-method-in-docs.md)
18
+
19
+
---
20
+
21
+
<include>(.issues/docs-not-cached.md)
uk/docs/api/rest-bundle/developers/known_issues/.issues/core-validation-400.md
новий файл +11
−0
1
+
### Помилки валідації повертають 400, а не 422
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 — 1.3 (поточна).
5
+
:::
6
+
7
+
**Симптом.** Порушення `#[RPC\Assertions]` чи неправильний тип параметра дають `400` з `RestBadRequestException`, хоча в таблиці помилок є `ConstraintsImposedException` → `422`.
8
+
9
+
**Причина.** Ядро RPC повертає помилку як RPC-помилку з кодом `-32602`; REST-шар відтворює з неї `RpcBadParamException`, а не `ConstraintsImposedException`. `422` отримує лише `ConstraintsImposedException`, що доходить до REST-шару напряму.
10
+
11
+
**Обхідний шлях.** Розраховуйте на `400` з повідомленнями по параметрах у `detail-data`.
uk/docs/api/rest-bundle/developers/known_issues/.issues/enum-not-cast.md
новий файл +11
−0
1
+
### Параметри-enum не конвертуються з рядка
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 — 1.3 (поточна).
5
+
:::
6
+
7
+
**Симптом.** `GET /rest/items?status=active` для параметра `Status $status` (backed enum) повертає `400` з помилкою типу.
8
+
9
+
**Причина.** Значення з query, шляху й форми — рядки; `RpcFromRest::castString()` приводить лише скалярні типи, а ядро RPC не конвертує рядок в enum — однаково для REST і JSON-RPC.
10
+
11
+
**Обхідний шлях.** Приймайте `string` і перетворюйте значення в методі (`Status::from($status)`).
uk/docs/api/rest-bundle/developers/known_issues/.issues/get-params-as-body.md
новий файл +11
−0
1
+
### Параметри GET-методів документуються як тіло запиту
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 — 1.3 (поточна).
5
+
:::
6
+
7
+
**Симптом.** В OpenAPI операція `GET` має `requestBody` з параметрами методу, а запит у колекції Postman — raw JSON-тіло. Генератори клієнтів і Postman надсилають параметри в тілі `GET`-запиту замість query string.
8
+
9
+
**Причина.** `OpenApiAdapter::buildParam()` і `PostmanAdapter::buildService()` додають усі параметри, крім змінних шляху, у тіло незалежно від HTTP-методу.
10
+
11
+
**Обхідний шлях.** Бандл приймає параметри з query string (див. [Параметри запиту](/docs/api/rest-bundle/requests)); для `GET`-методів передавайте їх у query вручну.
uk/docs/api/rest-bundle/developers/known_issues/.issues/single-http-method-in-docs.md
новий файл +11
−0
1
+
### Документується лише перший HTTP-метод маршруту
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 — 1.3 (поточна).
5
+
:::
6
+
7
+
**Симптом.** Метод з `#[Route(..., methods: ['GET', 'POST'])]` приймає обидва HTTP-методи, але в OpenAPI і Postman є лише операція `GET`.
8
+
9
+
**Причина.** `OpenApiAdapter::buildService()` бере `current($route->getMethods())`, `PostmanAdapter::buildService()` — `$route->getMethods()[0]`. Виявлено за кодом.
10
+
11
+
**Обхідний шлях.** Публікуйте метод з одним HTTP-методом.
uk/docs/api/rest-bundle/developers/known_issues/.issues/docs-not-cached.md
новий файл +11
−0
1
+
### Документація REST не кешується
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 — 1.3 (поточна).
5
+
:::
6
+
7
+
**Симптом.** Кожен запит `GET /rest`, `GET /rest/postman` заново будує документ; `ETag` і `304 Not Modified`, як у документації RPC, немає.
8
+
9
+
**Причина.** `RestEntryPointController::openapiAction()` / `postmanAction()` щоразу викликають адаптер; кешування документації JsonRpcBundle працює лише для маршрутів RPC.
10
+
11
+
**Обхідний шлях.** Кешуйте відповідь на рівні HTTP-кешу чи вебсервера або не відкривайте документацію в production.