docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/rest-bundle/developers/known_issues/open.md
new file +21
ā0
1
+
# Open issues
2
+
3
+
Known bugs and limitations of the current version of REST Bundle (1.3, not released yet; the latest release is 1.2.0): symptom, cause and workaround. Fixed ones are on the [Fixed issues](/docs/api/rest-bundle/developers/known_issues/fixed) page.
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)
en/docs/api/rest-bundle/developers/known_issues/.issues/core-validation-400.md
new file +11
ā0
1
+
### Validation errors return 400, not 422
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 ā 1.3 (current).
5
+
:::
6
+
7
+
**Symptom.** A `#[RPC\Assertions]` violation or a wrong parameter type gives `400` with `RestBadRequestException`, although the error table maps `ConstraintsImposedException` ā `422`.
8
+
9
+
**Cause.** The RPC core returns the error as an RPC error with code `-32602`; the REST layer recreates an `RpcBadParamException` from it, not a `ConstraintsImposedException`. Only a `ConstraintsImposedException` that reaches the REST layer directly gets `422`.
10
+
11
+
**Workaround.** Expect `400` with per-parameter messages in `detail-data`.
en/docs/api/rest-bundle/developers/known_issues/.issues/enum-not-cast.md
new file +11
ā0
1
+
### Enum parameters are not converted from a string
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 ā 1.3 (current).
5
+
:::
6
+
7
+
**Symptom.** `GET /rest/items?status=active` for a `Status $status` parameter (backed enum) returns `400` with a type error.
8
+
9
+
**Cause.** Query, path and form values are strings; `RpcFromRest::castString()` casts only scalar types, and the RPC core does not convert a string to an enum, equally for REST and JSON-RPC.
10
+
11
+
**Workaround.** Accept a `string` and convert the value in the method (`Status::from($status)`).
en/docs/api/rest-bundle/developers/known_issues/.issues/get-params-as-body.md
new file +11
ā0
1
+
### GET method parameters are documented as a request body
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 ā 1.3 (current).
5
+
:::
6
+
7
+
**Symptom.** In OpenAPI a `GET` operation has a `requestBody` with the method parameters, and the Postman collection request has a raw JSON body. Client generators and Postman send the parameters in the body of a `GET` request instead of the query string.
8
+
9
+
**Cause.** `OpenApiAdapter::buildParam()` and `PostmanAdapter::buildService()` put all parameters except path variables into the body regardless of the HTTP method.
10
+
11
+
**Workaround.** The bundle accepts parameters from the query string (see [Request parameters](/docs/api/rest-bundle/requests)); for `GET` methods pass them in the query manually.
en/docs/api/rest-bundle/developers/known_issues/.issues/single-http-method-in-docs.md
new file +11
ā0
1
+
### Only the first HTTP method of a route is documented
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 ā 1.3 (current).
5
+
:::
6
+
7
+
**Symptom.** A method with `#[Route(..., methods: ['GET', 'POST'])]` accepts both HTTP methods, but OpenAPI and Postman contain only the `GET` operation.
8
+
9
+
**Cause.** `OpenApiAdapter::buildService()` takes `current($route->getMethods())`, `PostmanAdapter::buildService()` takes `$route->getMethods()[0]`. Found in the code.
10
+
11
+
**Workaround.** Publish the method with a single HTTP method.
en/docs/api/rest-bundle/developers/known_issues/.issues/docs-not-cached.md
new file +11
ā0
1
+
### REST documentation is not cached
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 ā 1.3 (current).
5
+
:::
6
+
7
+
**Symptom.** Every `GET /rest`, `GET /rest/postman` request builds the document again; there is no `ETag` and `304 Not Modified` as in the RPC documentation.
8
+
9
+
**Cause.** `RestEntryPointController::openapiAction()` / `postmanAction()` call the adapter every time; JsonRpcBundle documentation caching works only for RPC routes.
10
+
11
+
**Workaround.** Cache the response at the HTTP cache or web server level, or do not expose the documentation in production.