mxHeadless
REST API gateway для headless-фронтендов на MODX 3. Ресурсы, объекты, OpenAPI, API keys и OAuth
- MODX 3
- PHP 8.1
Swagger и OpenAPI
mxHeadless строит спецификацию из RouteCollection и ObjectRegistry на текущей установке. Extras, зарегистрированные через OnMxHeadlessRegister, попадают в meta-маршруты вместе с core.
Публичные meta-маршруты работают без аутентификации.
Swagger UI
Интерактивная документация на:
text
GET /api/v1/docsUI грузит Swagger UI с CDN (версия из пакета) и подставляет spec с /api/v1/meta/openapi.json. Включён tryItOutEnabled и persistAuthorization: Bearer или API key, введённые в UI, сохраняются между перезагрузками страницы.
Выключатель: mxheadless_swagger_enabled (по умолчанию true). При false /docs отдаёт 404. Сырой OpenAPI JSON остаётся доступен.
На боевом сайте UI часто отключают, если документация снаружи не нужна. См. чеклист production.
Живой OpenAPI
В envelope (как остальные JSON-ответы API):
bash
curl -s https://example.com/api/v1/meta/openapi | jq '.data.openapi'Поле data — документ OpenAPI 3.0.3: пути, параметры, security schemes, теги.
Сырой JSON без envelope для Swagger UI и генераторов клиентов:
bash
curl -s https://example.com/api/v1/meta/openapi.json | jq '.openapi'Content-Type: application/openapi+json.
Каталог эндпоинтов
Список маршрутов с метаданными (core + extras через registerEndpoint):
bash
curl -s https://example.com/api/v1/meta/endpoints | jqПоля каждой записи:
| Поле | Смысл |
|---|---|
name | Имя маршрута (resources.create, objects.list, …) |
methods | Список HTTP-методов |
path | Публичный путь с плейсхолдерами |
pattern | То же, что path: роут и каталог отдают одинаковое значение |
public | Доступен ли anonymous |
permission | Строка scope или null |
object | Имя объекта из registry или null |
description | Текст описания или null |
tags | Список тегов |
parameters | Описания path- и query-параметров маршрута |
Discovery (GET /api/v1) ссылается на meta-URL в links. Полный список core-маршрутов: Обзор API.
Корень OpenAPI-документа содержит нестандартное расширение x-mxheadless.objects со списком всех зарегистрированных имён объектов. Генераторы клиентов его игнорируют, но по нему удобно проверить, какие объекты доступны на конкретной установке.
Schema vs OpenAPI
| Источник | Путь | Что описывает |
|---|---|---|
| Schema | GET /schema | Объекты из registry: fields, filterable, sortable, relations, флаги CRUD |
| OpenAPI | GET /meta/openapi, /meta/openapi.json | HTTP: методы, path/query params, коды ответов, security |
Schema удобен для построения клиента запросов. OpenAPI — для HTTP-контракта и генерации клиента. При регистрации нового object через Extension API обновляются schema и OpenAPI на сайте.
Генерация TypeScript-клиента
Укажите генератору /api/v1/meta/openapi.json, не /meta/openapi с обёрткой, если инструмент ждёт корневое поле openapi.
Пример с openapi-typescript:
bash
npx openapi-typescript https://your-site.example/api/v1/meta/openapi.json -o mxheadless.d.tsНа CI можно сверять статический openapi.yaml из репозитория mxHeadless с живой спецификацией на staging.