Актуальні помилки

Відомі помилки й обмеження поточної версії REST Bundle (1.3, ще не випущена; останній реліз — 1.2.0): симптом, причина та обхідний шлях. Виправлені — на сторінці Виправлені помилки.

<include>(.issues/core-validation-400.md)

<include>(.issues/enum-not-cast.md)

<include>(.issues/get-params-as-body.md)

<include>(.issues/single-http-method-in-docs.md)

<include>(.issues/docs-not-cached.md)

Помилки валідації повертають 400, а не 422

Симптом. Порушення #[RPC\Assertions] чи неправильний тип параметра дають 400 з RestBadRequestException, хоча в таблиці помилок є ConstraintsImposedException → 422.

Причина. Ядро RPC повертає помилку як RPC-помилку з кодом -32602; REST-шар відтворює з неї RpcBadParamException, а не ConstraintsImposedException. 422 отримує лише ConstraintsImposedException, що доходить до REST-шару напряму.

Обхідний шлях. Розраховуйте на 400 з повідомленнями по параметрах у detail-data.

Параметри-enum не конвертуються з рядка

Симптом. GET /rest/items?status=active для параметра Status $status (backed enum) повертає 400 з помилкою типу.

Причина. Значення з query, шляху й форми — рядки; RpcFromRest::castString() приводить лише скалярні типи, а ядро RPC не конвертує рядок в enum — однаково для REST і JSON-RPC.

Обхідний шлях. Приймайте string і перетворюйте значення в методі (Status::from($status)).

Параметри GET-методів документуються як тіло запиту

Симптом. В OpenAPI операція GET має requestBody з параметрами методу, а запит у колекції Postman — raw JSON-тіло. Генератори клієнтів і Postman надсилають параметри в тілі GET-запиту замість query string.

Причина. OpenApiAdapter::buildParam() і PostmanAdapter::buildService() додають усі параметри, крім змінних шляху, у тіло незалежно від HTTP-методу.

Обхідний шлях. Бандл приймає параметри з query string (див. Параметри запиту); для GET-методів передавайте їх у query вручну.

Документується лише перший HTTP-метод маршруту

Симптом. Метод з #[Route(..., methods: ['GET', 'POST'])] приймає обидва HTTP-методи, але в OpenAPI і Postman є лише операція GET.

Причина. OpenApiAdapter::buildService() бере current($route->getMethods()), PostmanAdapter::buildService() — $route->getMethods()[0]. Виявлено за кодом.

Обхідний шлях. Публікуйте метод з одним HTTP-методом.

Документація REST не кешується

Симптом. Кожен запит GET /rest, GET /rest/postman заново будує документ; ETag і 304 Not Modified, як у документації RPC, немає.

Причина. RestEntryPointController::openapiAction() / postmanAction() щоразу викликають адаптер; кешування документації JsonRpcBundle працює лише для маршрутів RPC.

Обхідний шлях. Кешуйте відповідь на рівні HTTP-кешу чи вебсервера або не відкривайте документацію в production.