Перейти к основному содержимому

ADR 0206 — Справочник API становится страницей Redoc

Статус​

Accepted. 2026-10-02 (AT-359; решение владельца от 02.10). Пересматривает, не редактируя, ADR 0033 в половине ПУБЛИКАЦИИ: spec по-прежнему берётся из кода (docs/reference/openapi.json, DTO по типу, табличный тест), а openapi:types:check в web не меняется.

Контекст​

ADR 0033 публиковал справочник через docusaurus-plugin-openapi-docs и docusaurus-theme-openapi-docs (5.1.2): 235 сгенерированных .mdx в docs/reference/api/, закреплённых манифестом хешей. Оба тянут postman-collection@5.3.1, который закрепляет @faker-js/faker@5.5.3 ТОЧНО — оповещение High #43, GHSA-qxc2-j82w-r537. Измерено 02.10: ни у одного родителя цепочки нет версии, уходящей от faker 5.5.3, а override на 10.x проваливает docs:build (API v5 удалён). Закрыть оповещение, сохранив плагин, было невозможно.

Решение​

Заменить пару пакетов на Redocusaurus (redocusaurus 2.5.x): ОДНА страница Redoc, с SSR, в /reference/api/, читаемая из той же docs/reference/openapi.json. Почему он: это preset Docusaurus 3, рендерит на сервере (страница выходит в HTML сборки, проверяемая без браузера), следует теме сайта и не тянет postman-collection и faker.

  • pnpm docs:generate перестаёт генерировать .mdx и манифест .openapi-manifest.json; docs/reference/api/ уходит из репозитория.
  • Боковая панель получает ССЫЛКУ на /reference/api/ вместо категории по тегу.
  • scripts/docs/api-render-check.mjs остаётся защитой после сборки (урок 0033: зелёная сборка — не страница, которая рендерится), теперь утверждая в HTML обоих языков заголовок spec и раздел на операцию.

Последствия​

  • Закрывает оповещение #43: @faker-js/faker и postman-collection уходят из дерева website/. Два override остались без потребителя и ушли (js-yaml@>=5.0.0 <5.2.2 и undici@>=6.0.0 <6.28.1, приходившие лишь через плагин), а также allowBuilds для postman-code-generators.
  • ПОТЕРИ, принятые владельцем: 235 страниц по операциям, боковая панель по тегу, URL по операциям (внешние ссылки на них ломаются), playground и сниппеты cURL.
  • Защита не открывает браузер: сбой гидратации Redoc не ловится; отсутствующая, пустая или без операций страница — ловится.