Чтение справочника OpenAPI

Pano описывает свой API сам. Отдельного справочника, который надо синхронизировать, нет: работающий сайт отвечает документом OpenAPI 3.1, и каждый плагин тоже.

Документы

Документ	URL	Содержимое
Ядро	/api/v1/openapi.json	Публичные операции Pano
Плагин	/api/v1/plugins/<pluginId>/_/openapi.json	Публичные операции этого плагина
Панель	/api/v1/panel/openapi.json	Внутренние операции, нужна сессия панели

Получите документ ядра с локального Pano:

curl -s http://localhost:8088/api/v1/openapi.json -o pano-openapi.json

Получите документ плагина market:

curl -s http://localhost:8088/api/v1/plugins/pano-plugin-market/_/openapi.json -o market-openapi.json

Плагинам ничего дополнительного не нужно: Pano строит документ из эндпоинтов плагина, в том числе для плагинов с закрытым кодом. У установленных, но остановленных плагинов документа нет.

Как читать операцию

• servers[0].url это префикс: /api/v1 для ядра, /api/plugins/<pluginId> для плагина. Пути операций идут после него.
• operationId это имя класса эндпоинта без API, например GetPosts. Типизированный клиент называет функции по нему.
• parameters и requestBody это JSON Schema, взятая из собственной валидации эндпоинта.
• responses перечисляет тело успеха и конверт ошибки. Общие коды ошибок (NOT_LOGGED_IN, NO_PERMISSION, INVALID_CSRF_TOKEN, RATE_LIMIT_EXCEEDED, MAINTENANCE_MODE_ENABLED) общие.
• deprecated: true значит, что замена существует; x-pano-removal это самая ранняя дата удаления.
• x-pano-stability равен public или internal. Обещание из Основ API несут только публичные операции.
• x-pano-undocumented: true значит, что автор не дал описания: путь и входные данные настоящие, ответ произвольный.

Быстрый просмотр

Выведите все публичные пути и методы через jq:

jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | "\(.) \($p)"' pano-openapi.json

Покажите одну операцию:

jq '.paths["/posts"].get' pano-openapi.json

Любой просмотрщик или генератор OpenAPI 3.1 читает эти файлы как есть.

Хранение копии

Сохраните документ рядом с кодом и сравнивайте после обновлений. Изменение, удаляющее операцию или поле ответа (кроме устаревших с истёкшим сроком), это ошибка: сообщите о ней.

Для JavaScript сам файл нужен редко. pano-client pull скачивает документ ядра и документы активных плагинов и превращает их в функции.

Чего в документах нет

• Сокеты реального времени: см. Доступ.
• Маршруты страниц фронтенда и резервные страницы /_pano/*: см. Быстрый старт фронтенда.
• Исходящие события: см. Вебхуки.