docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/rest-bundle/documentation.md
new file +90
ā0
1
+
# API documentation
2
+
3
+
Each REST entry point publishes two documents for each API version. They contain only the methods of that entry point's group and version, and its URL.
4
+
5
+
| Request | Response |
6
+
| --- | --- |
7
+
| `GET /rest` | An [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) document |
8
+
| `GET /rest/postman` | A Postman collection |
9
+
| `GET /rest/v2`, `GET /rest/v2/postman` | The same for [API version](/docs/api/json-rpc-bundle/functionality/versions) `v2` |
10
+
| `GET /internal`, ā¦ | The same for an [API group](/docs/api/rest-bundle/routing) entry point |
11
+
12
+
If `protected_doc: true` is set in the JsonRpcBundle settings, these requests require the group's token; see [Security](/docs/api/rest-bundle/security).
13
+
14
+
## What goes into OpenAPI
15
+
16
+
| Element | Source |
17
+
| --- | --- |
18
+
| `info.title`, `info.description` | `ufo_json_rpc.docs.project_name`, `project_description` |
19
+
| `info.version` | the requested API version |
20
+
| `info.x-versions` | all versions of the group |
21
+
| `servers[0].url` | the document URL from the current request |
22
+
| `servers[0].x-ufo` | envelope `REST (RFC 9110, 9457)/UFO-REST-<package version>`, environment, links to specifications |
23
+
| `paths.<path>.<method>` | one operation per REST route |
24
+
| `operationId` | the RPC method name (`catalog.item`) |
25
+
| `summary`, `description` | the method title and description (see below) |
26
+
| `tags` | the RPC procedure alias |
27
+
| `deprecated` | `@deprecated` or `#[\Deprecated]` on the method |
28
+
| `parameters` | path variables (`in: path`, required) with the method parameter's schema |
29
+
| `requestBody` | the other parameters as a JSON object: required flags, default values, descriptions, types, enums and DTO references |
30
+
| `responses.200` | the schema of the result type |
31
+
| `responses.<status>` | error statuses from `@throws` |
32
+
| `components.schemas` | DTOs and enums used by the operations |
33
+
34
+
```php
35
+
/**
36
+
* Returns an item by id
37
+
* @param int $id Item identifier
38
+
* @throws RpcDataNotFoundException
39
+
*/
40
+
#[Route('/items/{id}', name: 'item', methods: ['GET'])]
41
+
public function item(int $id): ItemDto
42
+
```
43
+
44
+
Here `@throws RpcDataNotFoundException` adds a `404` response to the operation: each exception from `@throws` is converted according to the [error table](/docs/api/rest-bundle/error_handling), one response per status. `@throws \Throwable` is documented as `RestApplicationException` (`400`).
45
+
46
+
Path variables are documented with their parameter's schema since 1.3; before that, as `string`.
47
+
48
+
## Postman collection
49
+
50
+
* The collection is named `REST: <project_name>`, with a ` [group]` suffix for a group other than `general` (since 1.2).
51
+
* Variables `base_url` (the host of the current request) and `apiToken`.
52
+
* Requests are grouped into folders by RPC procedure; each is named by its path.
53
+
* Each request has the route's HTTP method, a URL with Postman path variables (`/items/:id`), the `Content-Type` and token headers, and a raw JSON body with sample parameter values, except path variables.
54
+
55
+
## Translating titles and descriptions
56
+
57
+
:::info
58
+
Since version 1.3, requires JsonRpcBundle 10.4.
59
+
:::
60
+
61
+
Method titles and descriptions come from the JsonRpcBundle translations, the same as for the [RPC documentation](/docs/api/json-rpc-bundle/documentation):
62
+
63
+
```
64
+
translations/rpc.<locale>.yaml # base, for all groups
65
+
translations/rpc/<group>.<locale>.yaml # override for an API group
66
+
```
67
+
68
+
```yaml
69
+
# translations/rpc.en.yaml
70
+
catalog.item:
71
+
title: Item
72
+
description: Returns an item by id
73
+
```
74
+
75
+
Extension directories are added via `ufo_json_rpc.translations.paths`. The language is chosen from `Accept-Language` among the languages that have translations (`uk-UA` gives `uk`); the response gets `Content-Language` and `Vary: Accept-Language`.
76
+
77
+
| OpenAPI field | Value |
78
+
| --- | --- |
79
+
| `summary` | the translated title; without a title, the description; without both, the RPC method name |
80
+
| `description` | the translated description, if there is a title |
81
+
82
+
Postman collection requests get the translated description.
83
+
84
+
## Limitations
85
+
86
+
* Documents are generated on every request; there is no `ETag` caching as in the RPC documentation.
87
+
* For `GET` methods parameters are documented as a request body (`requestBody` in OpenAPI, raw JSON in Postman), although the bundle also accepts them from the query.
88
+
* For a route with several HTTP methods only the first one is documented.
89
+
90
+
See [Open issues](/docs/api/rest-bundle/developers/known_issues/open).