Документація API

Документація API

Кожен REST-вхід публікує два документи для кожної версії API. Вони містять лише методи групи й версії цього входу і його URL.

Запит Відповідь
GET /rest Документ OpenAPI 3.1
GET /rest/postman Колекція Postman
GET /rest/v2, GET /rest/v2/postman Те саме для версії API v2
GET /internal, … Те саме для входу групи API

Якщо в налаштуваннях JsonRpcBundle protected_doc: true, ці запити потребують токена групи — див. Безпека.

Що потрапляє в OpenAPI

Елемент Джерело
info.title, info.description ufo_json_rpc.docs.project_name, project_description
info.version запитана версія API
info.x-versions усі версії групи
servers[0].url URL документа з поточного запиту
servers[0].x-ufo envelope REST (RFC 9110, 9457)/UFO-REST-<версія пакета>, оточення, посилання на специфікації
paths.<шлях>.<метод> одна операція на REST-маршрут
operationId назва RPC-методу (catalog.item)
summary, description назва й опис методу (див. нижче)
tags псевдонім RPC-процедури
deprecated @deprecated або #[\Deprecated] на методі
parameters змінні шляху (in: path, обов'язкові) зі схемою параметра методу
requestBody решта параметрів як JSON-об'єкт: обов'язковість, значення за замовчуванням, описи, типи, enum і посилання на DTO
responses.200 схема типу результату
responses.<статус> статуси помилок з @throws
components.schemas DTO і enum, які використовують операції 
/**
 * Returns an item by id
 * @param int $id Item identifier
 * @throws RpcDataNotFoundException
 */
#[Route('/items/{id}', name: 'item', methods: ['GET'])]
public function item(int $id): ItemDto

Тут @throws RpcDataNotFoundException дає відповідь 404 в операції: кожен виняток з @throws перетворюється за таблицею помилок, на кожен статус — одна відповідь. @throws \Throwable документується як RestApplicationException (400).

Змінні шляху документуються схемою свого параметра з 1.3; раніше — як string.

Колекція Postman

  • Назва колекції — REST: <project_name>, для групи, відмінної від general, — з суфіксом [група] (з 1.2).
  • Змінні base_url (хост поточного запиту) і apiToken.
  • Запити згруповані в теки за RPC-процедурою; кожен названо його шляхом.
  • Кожен запит має HTTP-метод маршруту, URL зі змінними шляху у форматі Postman (/items/:id), заголовки Content-Type і токена та raw JSON-тіло з прикладами значень параметрів, крім змінних шляху.

Переклад назв і описів

З версії 1.3, потрібен JsonRpcBundle 10.4.

Назви й описи методів беруться з перекладів JsonRpcBundle — так само, як для документації RPC:

translations/rpc.<locale>.yaml          # база, для всіх груп
translations/rpc/<group>.<locale>.yaml  # перевизначення для групи API

# translations/rpc.uk.yaml
catalog.item:
    title: Товар
    description: Повертає товар за ідентифікатором

Теки розширень підключаються через ufo_json_rpc.translations.paths. Мова вибирається з Accept-Language серед мов, для яких є переклади (uk-UA дає uk); відповідь отримує Content-Language і Vary: Accept-Language.

Поле OpenAPI Значення
summary перекладена назва; без назви — опис; без обох — назва RPC-методу
description перекладений опис, якщо є назва

Запити колекції Postman отримують перекладений опис.

Обмеження

  • Документи генеруються на кожен запит; кешування з ETag, як у документації RPC, немає.
  • Для GET-методів параметри документуються як тіло запиту (requestBody в OpenAPI, raw JSON у Postman), хоча бандл приймає їх і з query.
  • Для маршруту з кількома HTTP-методами документується лише перший.

Див. Актуальні помилки.