docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/rest-bundle/installation.md
новий файл +110
−0
1
+
# Встановлення REST Bundle
2
+
3
+
:::info
4
+
Вимоги: PHP ^8.4, Symfony ^7.2 або ^8.0, `cebe/php-openapi` ^1.8 і `ufo-tech/json-rpc-bundle` — ^10.2.3 для 1.2, ^10.4.2 для 1.3 (ще не випущена).
5
+
:::
6
+
7
+
Застосунок уже має обслуговувати [JsonRpcBundle](/docs/api/json-rpc-bundle/installation): REST Bundle використовує його карту методів, налаштування `ufo_json_rpc`, безпеку й переклади.
8
+
9
+
## Крок 0: Налаштування composer.json
10
+
11
+
Щоб Symfony Flex автоматично зареєстрував бандл і створив файл маршрутів, додайте репозиторій рецептів UFO-Tech у ваш `composer.json` (так само, як для [JsonRpcBundle](/docs/api/json-rpc-bundle/installation)):
12
+
13
+
```json
14
+
{
15
+
"extra" : {
16
+
"symfony": {
17
+
"endpoint": [
18
+
"https://api.github.com/repos/ufo-tech/recipes/contents/index.json?ref=main",
19
+
"flex://defaults"
20
+
]
21
+
}
22
+
}
23
+
}
24
+
```
25
+
26
+
## Крок 1: Встановлення
27
+
28
+
```bash
29
+
composer require ufo-tech/rest-bundle
30
+
```
31
+
32
+
## Крок 2: Реєстрація пакета
33
+
34
+
Переконайтесь, що бандл зареєстровано в `config/bundles.php` після JsonRpcBundle:
35
+
36
+
```php
37
+
return [
38
+
// ...
39
+
Ufo\JsonRpcBundle\UfoJsonRpcBundle::class => ['all' => true],
40
+
Ufo\RestBundle\RestBundleBundle::class => ['all' => true],
41
+
];
42
+
```
43
+
44
+
## Крок 3: Реєстрація маршрутів
45
+
46
+
:::warning
47
+
Якщо ви виконали **«Крок 0»**, файл створено автоматично і цей крок можна пропустити.
48
+
:::
49
+
50
+
Додайте файл `config/routes/ufo_rest_api.yaml` (шаблон лежить у пакеті: `install/routes/ufo_rest_api.yaml`):
51
+
52
+
```yaml
53
+
# config/routes/ufo_rest_api.yaml
54
+
ufo_rest_api:
55
+
resource: ../../vendor/ufo-tech/rest-bundle/config/router.yaml
56
+
prefix: /rest
57
+
trailing_slash_on_root: false
58
+
```
59
+
60
+
`prefix` — адреса REST-входу. Окремі входи для [груп API](/docs/api/json-rpc-bundle/functionality/groups) описано в розділі [Маршрутизація](/docs/api/rest-bundle/routing).
61
+
62
+
Окремого конфігураційного файлу бандл не має — див. [Налаштування](/docs/api/rest-bundle/config).
63
+
64
+
## Крок 4: Перший REST-метод
65
+
66
+
Додайте атрибут Symfony `#[Route]` до методу наявної RPC-процедури:
67
+
68
+
```php
69
+
use Symfony\Component\Routing\Attribute\Route;
70
+
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
71
+
use Ufo\RpcObject\RPC;
72
+
73
+
#[RPC\Info('catalog')]
74
+
#[Route('/catalog', name: 'catalog')]
75
+
class CatalogApi implements IRpcService
76
+
{
77
+
#[Route('/items', name: 'list', methods: ['GET'])]
78
+
public function list(int $page = 1): array
79
+
{
80
+
return ['page' => $page, 'items' => []];
81
+
}
82
+
}
83
+
```
84
+
85
+
## Перевірка
86
+
87
+
| Запит | Що повертає |
88
+
| --- | --- |
89
+
| `GET /rest` | Документ OpenAPI 3.1 |
90
+
| `GET /rest/postman` | Колекцію Postman |
91
+
| `GET /rest/catalog/items?page=2` | Результат `catalog.list` |
92
+
93
+
```bash
94
+
curl 'https://example.com/rest/catalog/items?page=2' \
95
+
-H 'Ufo-RPC-Token: change-me'
96
+
```
97
+
98
+
```json
99
+
{"page": 2, "items": []}
100
+
```
101
+
102
+
Приведення `"2"` з query до `int` з'явилось у 1.3; у 1.2 такий запит повертає `400` (див. [Параметри запиту](/docs/api/rest-bundle/requests)).
103
+
104
+
Токен потрібен, якщо в налаштуваннях JsonRpcBundle `protected_api: true` (за замовчуванням). Назви згенерованих маршрутів показує `bin/console debug:router | grep ufo_rest`.
105
+
106
+
## Що далі?
107
+
108
+
* [Маршрутизація](/docs/api/rest-bundle/routing) — правила шляхів і імен, версії, групи API.
109
+
* [Параметри запиту](/docs/api/rest-bundle/requests) — звідки беруться параметри методу.
110
+
* [Безпека](/docs/api/rest-bundle/security) — токени для викликів і документації.