Генерация документа

Этот API позволяет внешнему сервису запросить готовый HTML-документ с серверной сборкой без входа в editor.

Что делает API

Это удобно, когда итоговую документацию нужно собирать в CI, готовить по webhook, отдавать из внутреннего сервиса или генерировать на лету из шаблона и переменных.

Механизм настраивается на уровне document и не связан с внешним обновлением контента section. Внешнее обновление меняет содержимое конкретного section, а этот API возвращает целиком сгенерированный HTML-документ.

Как включить

  1. Откройте нужный document в workspace.
  2. Перейдите в настройки document.
  3. Откройте блок API генерации документа.
  4. Включите API и сохраните document.
  5. Скопируйте выданный secret key и endpoint.

Функция доступна только на тарифе Pro. Если API выключить, ключ сразу очищается. Если ключ скомпрометирован, его нужно перевыпустить и обновить интеграцию.

Endpoint и авторизация

Запрос отправляется на серверный endpoint:

POST /api/document-generate/:syncKey

Вместо :syncKey подставляется секретный ключ конкретного document. Отдельного заголовка авторизации у метода нет: доступ полностью держится на знании ключа.

По этой причине ключ нужно хранить как секрет, не вставлять в публичный frontend-код и не писать в открытые логи.

Что возвращает endpoint

При успешном вызове сервер возвращает 200 OK и сразу отдает сгенерированный HTML-документ как файл для скачивания.

Ответ приходит с типом text/html; charset=utf-8. JSON при успехе здесь не возвращается.

Формат запроса

API принимает JSON. Все поля тела запроса опциональны. Если тело пустое, сервер собирает document в текущем сохраненном состоянии.

{
  "variables": [
    { "key": "productName", "value": "Atlas SDK" }
  ],
  "pages": [
    {
      "sectionId": "release-notes",
      "title": "Release notes",
      "content": "<h1>Release notes</h1><p>Generated in CI.</p>"
    }
  ],
  "styles": {
    "customCss": ".hero { color: #0f172a; }",
    "externalCssUrls": ["https://cdn.example.com/docs.css"],
    "minifyCss": true
  },
  "scripts": {
    "customScripts": "console.log('generated');",
    "externalScriptUrls": ["https://cdn.example.com/docs.js"],
    "minifyScripts": true
  }
}

variables заменяет document variables на время генерации. Можно передать полный набор переменных и собрать тот же document с другим набором значений.

pages позволяет переопределить содержимое и заголовки конкретных страниц на время генерации. Поддерживаются section типов page, API Reference и link.

Для API Reference в pages[].content нужно передавать строку с валидным extractor JSON, а не HTML.

styles и scripts позволяют временно подменить document-level CSS, JS и внешние asset URL для текущей генерации. Эти поля тоже доступны только для Pro, как и весь API.

const endpoint = "https://onefiledocs.com/api/document-generate/DOCUMENT_SECRET";

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    variables: [
      { key: "productName", value: "Atlas SDK" },
    ],
    pages: [
      {
        sectionId: "release-notes",
        content: "<h1>Release notes</h1><p>Generated in CI.</p>",
      },
    ],
  }),
});

const html = await response.text();

Если интеграции нужен именно текст HTML, его можно прочитать через response.text(). Если нужен файл, можно использовать тело ответа как blob и сохранять его без дополнительного JSON-парсинга.

Ошибки и ограничения

Если тело запроса некорректно, указан несуществующий section для переопределения страницы или передан невалидный extractor JSON для API Reference, сервер вернет 400 Bad Request.

Если API генерации выключен для document или у владельца документа больше нет активного Pro, сервер вернет 403 Forbidden.

Если ключ не найден, сервер вернет 404 Not Found.

Сервер всегда собирает один итоговый HTML-документ. Переключения формата ответа у этого endpoint нет.