Встановлення REST Bundle

← Встановлення REST Bundle

Ashterix

docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api

uk/docs/api/rest-bundle/installation.md новий файл +110 −0

Встановлення REST Bundle

Вимоги: 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 (ще не випущена).

Застосунок уже має обслуговувати JsonRpcBundle: REST Bundle використовує його карту методів, налаштування ufo_json_rpc, безпеку й переклади.

Крок 0: Налаштування composer.json

Щоб Symfony Flex автоматично зареєстрував бандл і створив файл маршрутів, додайте репозиторій рецептів UFO-Tech у ваш composer.json (так само, як для JsonRpcBundle):

{
    "extra" : {
        "symfony": {
            "endpoint": [
                "https://api.github.com/repos/ufo-tech/recipes/contents/index.json?ref=main",
                "flex://defaults"
            ]
        }
    }
}

Крок 1: Встановлення

composer require ufo-tech/rest-bundle

Крок 2: Реєстрація пакета

Переконайтесь, що бандл зареєстровано в config/bundles.php після JsonRpcBundle:

return [
    // ...
    Ufo\JsonRpcBundle\UfoJsonRpcBundle::class => ['all' => true],
    Ufo\RestBundle\RestBundleBundle::class => ['all' => true],
];

Крок 3: Реєстрація маршрутів

Якщо ви виконали «Крок 0», файл створено автоматично і цей крок можна пропустити.

Додайте файл config/routes/ufo_rest_api.yaml (шаблон лежить у пакеті: install/routes/ufo_rest_api.yaml):

# config/routes/ufo_rest_api.yaml
ufo_rest_api:
    resource: ../../vendor/ufo-tech/rest-bundle/config/router.yaml
    prefix: /rest
    trailing_slash_on_root: false

prefix — адреса REST-входу. Окремі входи для груп API описано в розділі Маршрутизація.

Окремого конфігураційного файлу бандл не має — див. Налаштування.

Крок 4: Перший REST-метод

Додайте атрибут Symfony #[Route] до методу наявної RPC-процедури:

use Symfony\Component\Routing\Attribute\Route;
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
use Ufo\RpcObject\RPC;

#[RPC\Info('catalog')]
#[Route('/catalog', name: 'catalog')]
class CatalogApi implements IRpcService
{
    #[Route('/items', name: 'list', methods: ['GET'])]
    public function list(int $page = 1): array
    {
        return ['page' => $page, 'items' => []];
    }
}

Перевірка

Запит Що повертає
GET /rest Документ OpenAPI 3.1
GET /rest/postman Колекцію Postman
GET /rest/catalog/items?page=2 Результат catalog.list 
curl 'https://example.com/rest/catalog/items?page=2' \
  -H 'Ufo-RPC-Token: change-me'

{"page": 2, "items": []}

Приведення "2" з query до int з'явилось у 1.3; у 1.2 такий запит повертає 400 (див. Параметри запиту).

Токен потрібен, якщо в налаштуваннях JsonRpcBundle protected_api: true (за замовчуванням). Назви згенерованих маршрутів показує bin/console debug:router | grep ufo_rest.

Що далі?