Каталог и OpenAPI

Каталог собирается из живого реестра эндпоинтов: он показывает то, что сайт умеет прямо сейчас. Отдельного файла спецификации, который живёт рядом с кодом и потихоньку от него отстаёт, в mxApi нет.

Смотреть каталог можно тремя способами.

В админке

Компоненты → mxApi — каталог только на чтение: маршрут, методы, scope, право MODX, параметры, пример curl, источник эндпоинта (ядро, пакет или проект). Там же кнопка выгрузки OpenAPI.

Это же место отвечает на вопрос «что вообще можно запросить в scope» при выпуске токена.

GET /meta/endpoints

Тот же каталог машиночитаемо (scope meta.read):

curl 'https://site.ru/mxapi/v1/meta/endpoints' \
  -H 'Authorization: Bearer <token>'

{
  "success": true,
  "data": [
    {
      "id": "meta.endpoints",
      "title": "Каталог эндпоинтов",
      "path": "/meta/endpoints",
      "methods": ["GET"],
      "scope": "meta.read",
      "permission": "mxapi_meta_read",
      "parameters": []
    }
  ],
  "meta": {
    "count": 1,
    "route_prefix": "/mxapi/v1",
    "filter": "all"
  }
}

В meta.filter возвращается активный режим видимости — чтобы короткий каталог не выглядел как «эндпоинтов на сайте нет».

Маршрут отдаётся без шаблонов роутера: наружу идёт /orders/{id}, а не /orders/{id:\d+}.

GET /meta/openapi

Спецификация OpenAPI 3.0, построенная по метаданным зарегистрированных эндпоинтов:

curl 'https://site.ru/mxapi/v1/meta/openapi' \
  -H 'Authorization: Bearer <token>' -o openapi.json

Документ отдаётся как есть, без конверта success/data: иначе его не примет ни один инструмент, работающий с OpenAPI. Файл можно передать интегратору или загрузить в Swagger UI либо Postman.

Что в каталог не попадает

Детали реализации. Из публичного представления эндпоинта вырезаны processor, processors_path, field_map и properties: это внутреннее устройство обёртки над процессором MODX, а не контракт. В админке они видны, наружу не уходят.

Служебные эндпоинты. Эндпоинт, помеченный как внутренний, не отдаётся ни в /meta/endpoints, ни в OpenAPI никогда, ни при каком режиме видимости. Так помечают то, что завязано на сессию, корзину или черновик заказа: интегратор принял бы такой маршрут за часть контракта.

Режимы видимости

Настройка mxapi.catalog_filter:

Режим	Что видно
all (по умолчанию)	весь публичный контракт сайта — каталог работает как документация: интегратор видит, какие scope существуют и что просить
scope	только то, что можно вызвать предъявленным токеном
permission	только то, на что у пользователя есть право MODX, независимо от scope текущего токена

Ужесточать режим имеет смысл там, где на сайте живут несколько независимых интеграций: при all клиент одной видит состав эндпоинтов другой вместе с именами прав. Данные при этом недоступны — вызов даст insufficient_scope или insufficient_permission, — но поверхность записи раскрывается.

Режим влияет только на видимость. Доступ всегда решают scope и право MODX: спрятанный из каталога эндпоинт не становится закрытым, а показанный — открытым.