Справочник: сайдбар документации

Ручки сайта: $API/site/$SITE/docs/sidebar…. Пункт — страница, собираемая фреймом документации; вложенность — родитель, порядок — menu_order. frame (слаг или id, в теле или строке запроса) во всех ручках называет фрейм документации явно; без него — опция сайта, затем слаги docs, obolochka-dokumentaciya. Ссылка на пункт — id, слаг, путь (в пути адреса — с тильдами) или объект {id|slug|url}. Как устроено — сайдбар документации.

Примеры ниже сняты на этой самой документации (сайт onpress.pro).

GET /docs/sidebar

Параметр	По умолчанию	Смысл
`lang`	все языки	только страницы языка
`include_hidden`	`false`	со скрытыми пунктами
`statuses`	`publish,draft,private,pending,future`	статусы через запятую (синоним `status`)
`public`	`false`	то же, что `statuses=publish`
`frame`	—	фрейм документации

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/docs/sidebar?lang=ru&public=1"

{
  "success": true,
  "site_id": "ef7QmgyEc",
  "home_url": "https://onpress.pro",
  "frame": { "id": "fd26d10638458973", "slug": "docs" },
  "frame_source": "default",
  "template": "templates/docs.php",
  "statuses": ["publish"],
  "include_hidden": false,
  "lang": { "requested": "ru", "applied": "ru", "filtered_out": 0 },
  "total": 45,
  "hidden_total": 0,
  "tree": [
    {
      "id": 6249,
      "title": "Документация OnPress v2",
      "slug": "v2",
      "status": "publish",
      "parent": 4934,
      "menu_order": 0,
      "hidden": false,
      "lang": "ru",
      "url": "/docs/v2/",
      "link": "https://onpress.pro/docs/v2/",
      "children": [
        { "id": 6250, "title": "Как устроена платформа", "slug": "ustrojstvo", "status": "publish", "parent": 6249, "menu_order": 1, "hidden": false, "lang": "ru", "url": "/docs/v2/ru/how-it-works/", "link": "https://onpress.pro/docs/v2/ru/how-it-works/", "children": [] }
      ]
    }
  ]
}

frame_source — откуда взят фрейм: param, option, default. total — узлов в дереве, hidden_total — из них скрытых. link у черновика — null. Отказы: 400 bad_status (allowed), 422 unknown_language, 404 docs_frame_not_found.

PUT /docs/sidebar

Положить дерево целиком — одна транзакция.

Поле	По умолчанию	Смысл
`items`	—	дерево (синоним `tree`); пункт — ссылка плюс `title`, `status`, `hidden`, `children`
`missing`	`hide`	что делать со страницами документации вне дерева: `hide` или `keep`
`lang`	язык пунктов	языковая ветка, которую заменяет запрос
`dry_run`	`false`	показать изменения и откатить
`frame`	—	фрейм документации

Ответ: applied, dry_run, lang, items (сколько пунктов), changes ([{id, title?, status?, parent?, menu_order?, hidden, frame?}] с from/to), moved ([{id, url_before, url_after}]), dropped (скрытые), warnings, notified.

Отказы: 400 bad_items, 400 bad_missing, 409 sidebar_items_unresolved (errors: [{at, ref, error}] — ничего не применено), 409 duplicate_item, 422 unknown_language.

POST /docs/sidebar/reorder

Поле	Смысл
`parent` + `order`	ветка и её пункты по порядку; неназванные — после (`appended`)
`id` + `after` / `before` / `position`	переставить один пункт

curl -s -X POST "$API/site/$SITE/docs/sidebar/reorder" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"parent": 4934, "order": [6249, 6248]}'

{ "success": true, "site_id": "ef7QmgyEc", "parent": 4934, "order": [6249, 6248], "appended": [], "updated": 2, "notified": 2 }

Нумерация menu_order в ветке — подряд с нуля. Отказы: 400 bad_reorder, 409 not_a_sibling, 404 page_not_found, 409 ambiguous_page.

PATCH /docs/sidebar/items/{ref}

Поле	Смысл
`title`	новый заголовок страницы
`status`	`publish`, `draft`, `private`, `pending`, `future`
`parent`	новый родитель (id, слаг, путь или `0`) — меняет адрес страницы и поддерева
`hidden`	спрятать или вернуть
`after`, `before`, `position`	место среди соседей (после смены родителя)

Ответ: item (id и изменённые поля в виде {from, to}, url_before, url, old_paths при переносе, menu_order), warnings, notified. Отказы: 400 nothing_to_update, 400 item_ref_required, 404 page_not_found, 409 ambiguous_page, 422 parent_not_found.

POST /docs/sidebar/items/{ref}/hide и /show

Тело не нужно (кроме frame при необходимости).

{ "success": true, "site_id": "ef7QmgyEc", "item": { "id": 6300, "title": "…", "hidden": true, "status": "publish", "url": "/docs/v2/…/" }, "warnings": [], "notified": 1 }

Скрытие раздела с видимыми детьми даёт предупреждение: дети поднимутся в корень.