docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/rest-bundle/documentation.md
новий файл +90
−0
1
+
# Документація API
2
+
3
+
Кожен REST-вхід публікує два документи для кожної версії API. Вони містять лише методи групи й версії цього входу і його URL.
4
+
5
+
| Запит | Відповідь |
6
+
| --- | --- |
7
+
| `GET /rest` | Документ [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) |
8
+
| `GET /rest/postman` | Колекція Postman |
9
+
| `GET /rest/v2`, `GET /rest/v2/postman` | Те саме для [версії API](/docs/api/json-rpc-bundle/functionality/versions) `v2` |
10
+
| `GET /internal`, … | Те саме для входу [групи API](/docs/api/rest-bundle/routing) |
11
+
12
+
Якщо в налаштуваннях JsonRpcBundle `protected_doc: true`, ці запити потребують токена групи — див. [Безпека](/docs/api/rest-bundle/security).
13
+
14
+
## Що потрапляє в OpenAPI
15
+
16
+
| Елемент | Джерело |
17
+
| --- | --- |
18
+
| `info.title`, `info.description` | `ufo_json_rpc.docs.project_name`, `project_description` |
19
+
| `info.version` | запитана версія API |
20
+
| `info.x-versions` | усі версії групи |
21
+
| `servers[0].url` | URL документа з поточного запиту |
22
+
| `servers[0].x-ufo` | envelope `REST (RFC 9110, 9457)/UFO-REST-<версія пакета>`, оточення, посилання на специфікації |
23
+
| `paths.<шлях>.<метод>` | одна операція на REST-маршрут |
24
+
| `operationId` | назва RPC-методу (`catalog.item`) |
25
+
| `summary`, `description` | назва й опис методу (див. нижче) |
26
+
| `tags` | псевдонім RPC-процедури |
27
+
| `deprecated` | `@deprecated` або `#[\Deprecated]` на методі |
28
+
| `parameters` | змінні шляху (`in: path`, обов'язкові) зі схемою параметра методу |
29
+
| `requestBody` | решта параметрів як JSON-об'єкт: обов'язковість, значення за замовчуванням, описи, типи, enum і посилання на DTO |
30
+
| `responses.200` | схема типу результату |
31
+
| `responses.<статус>` | статуси помилок з `@throws` |
32
+
| `components.schemas` | DTO і enum, які використовують операції |
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
+
Тут `@throws RpcDataNotFoundException` дає відповідь `404` в операції: кожен виняток з `@throws` перетворюється за [таблицею помилок](/docs/api/rest-bundle/error_handling), на кожен статус — одна відповідь. `@throws \Throwable` документується як `RestApplicationException` (`400`).
45
+
46
+
Змінні шляху документуються схемою свого параметра з 1.3; раніше — як `string`.
47
+
48
+
## Колекція Postman
49
+
50
+
* Назва колекції — `REST: <project_name>`, для групи, відмінної від `general`, — з суфіксом ` [група]` (з 1.2).
51
+
* Змінні `base_url` (хост поточного запиту) і `apiToken`.
52
+
* Запити згруповані в теки за RPC-процедурою; кожен названо його шляхом.
53
+
* Кожен запит має HTTP-метод маршруту, URL зі змінними шляху у форматі Postman (`/items/:id`), заголовки `Content-Type` і токена та raw JSON-тіло з прикладами значень параметрів, крім змінних шляху.
54
+
55
+
## Переклад назв і описів
56
+
57
+
:::info
58
+
З версії 1.3, потрібен JsonRpcBundle 10.4.
59
+
:::
60
+
61
+
Назви й описи методів беруться з перекладів JsonRpcBundle — так само, як для [документації RPC](/docs/api/json-rpc-bundle/documentation):
62
+
63
+
```
64
+
translations/rpc.<locale>.yaml # база, для всіх груп
65
+
translations/rpc/<group>.<locale>.yaml # перевизначення для групи API
66
+
```
67
+
68
+
```yaml
69
+
# translations/rpc.uk.yaml
70
+
catalog.item:
71
+
title: Товар
72
+
description: Повертає товар за ідентифікатором
73
+
```
74
+
75
+
Теки розширень підключаються через `ufo_json_rpc.translations.paths`. Мова вибирається з `Accept-Language` серед мов, для яких є переклади (`uk-UA` дає `uk`); відповідь отримує `Content-Language` і `Vary: Accept-Language`.
76
+
77
+
| Поле OpenAPI | Значення |
78
+
| --- | --- |
79
+
| `summary` | перекладена назва; без назви — опис; без обох — назва RPC-методу |
80
+
| `description` | перекладений опис, якщо є назва |
81
+
82
+
Запити колекції Postman отримують перекладений опис.
83
+
84
+
## Обмеження
85
+
86
+
* Документи генеруються на кожен запит; кешування з `ETag`, як у документації RPC, немає.
87
+
* Для `GET`-методів параметри документуються як тіло запиту (`requestBody` в OpenAPI, raw JSON у Postman), хоча бандл приймає їх і з query.
88
+
* Для маршруту з кількома HTTP-методами документується лише перший.
89
+
90
+
Див. [Актуальні помилки](/docs/api/rest-bundle/developers/known_issues/open).