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

Этот 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 в текущем сохраненном состоянии.

{
  "saveContent": true,
  "variables": [
    { "key": "productName", "value": "Atlas SDK" }
  ],
  "pages": [
    {
      "sectionId": "release-notes",
      "title": "Release notes",
      "content": "<h1>Release notes</h1><p>Generated in CI.</p>",
      "saveContent": false
    },
    {
      "sectionId": "build-report",
      "type": "page",
      "title": "Build report",
      "content": "<h1>Build report</h1><p>This page exists only in the generated file.</p>",
      "parentSectionId": "release-notes",
      "position": 10
    }
  ],
  "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, dynamic и link. Для dynamic сохраняются настроенные в editor размещение навигации и видимость корневой страницы в TOC.

Если pages[].sectionId не совпадает с сохраненным section, API добавляет временный section в генерируемый document. Временные section никогда не сохраняются, даже если корневой или локальный saveContent имеет значение true. По умолчанию используется тип page. Поле parentSectionId позволяет поместить section внутрь сохраненного или ранее указанного в том же запросе временного section, а position задает порядок. Без родителя section добавляется в конец корневого уровня document.

Для временного section также доступны обычные параметры отображения: title, content, link, target, hiddenInMenu, generatesToc, sectionLanguage, собственные CSS и scripts, URL внешних ресурсов, флаги минификации и настройки навигации dynamic section. Для временных section типов API Reference и dynamic нужно передать валидный content.

По умолчанию saveContent имеет значение false. Значение true в корне запроса сохраняет на сервере все переданные значения pages[].content после успешной сборки document. Поле pages[].saveContent переопределяет общую настройку для конкретного section. Сохраняется только контент section типов page, API Reference и dynamic; заголовки, ссылки, variables, styles и scripts остаются временными параметрами генерации.

Для 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({
    saveContent: true,
    variables: [
      { key: "productName", value: "Atlas SDK" },
    ],
    pages: [
      {
        sectionId: "release-notes",
        content: "<h1>Release notes</h1><p>Generated in CI.</p>",
        saveContent: true,
      },
    ],
  }),
});

const html = await response.text();

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

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

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

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

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

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