Документирование API в базе знаний Chatonio

В базе знаний Chatonio есть встроенный блок API-эндпоинта: он отображает один HTTP-эндпоинт с методом, путём, описанием и несколькими примерами запросов и ответов — в том же виде, что и документация Stripe и других API. Каждый блок живёт внутри статьи рядом с обычным текстом, поэтому одна статья может описывать функцию человеческим языком и документировать её эндпоинты в том же месте. ИИ опирается на этот же текст, так что у клиентов и у ассистента остаётся один источник правды.

Шаг 1 — откройте редактор статьи

Перейдите в Админ → Проекты → [ваш проект] → База знаний, выберите (или создайте) категорию и нажмите «Новая статья». Откроется WYSIWYG-редактор Tiptap.

Шаг 2 — вставьте блок API-эндпоинта

На панели инструментов редактора нажмите кнопку «Вставить эндпоинт API» (иконка из двух горизонтальных полос). В документ на месте курсора вставится карточка с заполненными значениями по умолчанию — просто перепишите их.

Шаг 3 — метод, путь и описание

• Метод — выпадающий список, каждый глагол своего цвета (GET зелёный, POST синий, PUT/PATCH янтарный, DELETE красный). Плашка в опубликованной статье получает тот же цвет.
• Путь — путь эндпоинта, например /v1/orders/{order_id}/refund. Плейсхолдеры в фигурных скобках сохраняются как есть.
• Описание — одно-два предложения о том, что делает эндпоинт и когда его использовать. Именно это ИИ видит первым.

Шаг 4 — добавьте примеры запросов

Раздел «Запрос» начинается с одного примера с меткой Default. Нажмите «+ Добавить пример», чтобы добавить ещё — это удобно, когда один эндпоинт принимает и JSON-тело, и form-encoded, или когда у разных сценариев разная структура (частичный возврат против полного, например). У каждого примера своя метка, свой выбор языка и своё тело. Выбирайте язык, чтобы в опубликованном виде код получил правильную подсветку синтаксиса.

Шаг 5 — добавьте примеры ответов (успешные и с ошибкой)

Здесь большинство документаций и не дотягивает. Раздел «Ответы» принимает сколько угодно примеров, у каждого свой HTTP-код. Коды подсвечиваются по группам и в редакторе, и в опубликованной статье:

• 2xx — зелёный, успех.
• 3xx — синий, редирект.
• 4xx — янтарный, ошибка клиента.
• 5xx — красный, ошибка сервера.

Опишите хотя бы один успешный ответ и самые частые ошибки, с которыми столкнутся клиенты (400 — ошибка валидации, 404 — не найдено, 409 — конфликт). ИИ видит их все сразу, поэтому, когда клиент присылает текст ошибки, ассистент находит нужную запись сам — отдельную статью с разбором проблем писать не нужно.

Шаг 6 — обычный код оформляйте кодовым блоком

Для сниппетов SDK, конфигов, команд оболочки и прочего используйте обычную кнопку кодового блока на панели инструментов. Когда курсор внутри кодового блока, рядом с панелью появляется выбор языка; выберите json, bash, http, javascript или typescript, чтобы включить подсветку:

$ curl https://api.example.com/v1/health \
    -H "Authorization: Bearer $TOKEN"

И в редакторе, и в опубликованной статье при наведении появляется кнопка копирования.

Пример — эндпоинт возврата

Вот как выглядит блок эндпоинта после публикации. Клиент видит оформленную карточку; ИИ получает тот же текст, приведённый к аккуратному списку: метод, путь, описание, примеры.

{
  "amount_cents": 1500,
  "reason": "customer_request",
  "request_id": "req_a3f8"
}

{
  "reason": "duplicate_charge",
  "request_id": "req_b2c9"
}

{
  "id": "rf_29df",
  "order_id": "ord_8821",
  "amount_cents": 1500,
  "status": "succeeded"
}

{
  "error": "amount_cents exceeds order total"
}

{
  "error": "order not found"
}

{
  "error": "order already fully refunded"
}

Советы

• Один эндпоинт — один блок. Не запихивайте два эндпоинта в одну карточку: потеряется цветовая маркировка, и ИИ будет опираться на текст хуже.
• Держите примеры короткими и правдоподобными. И клиенты, и ИИ хуже усваивают ответ на 50 строк, чем на 5.
• Документируйте ошибки. Клиенты присылают текст ошибки — ИИ сопоставляет его с описанным ответом и отвечает с первого раза.
• Видимость имеет значение. Уровней три: PUBLIC публикует статью на публичном хелпдеске для всех; CLIENT показывает её только авторизованным клиентам хелпдеска — то, что нужно для документации API, предназначенной вашим клиентам; INTERNAL оставляет её только операторам. ИИ опирается на статью на любом уровне, если на ней включён ИИ, — видимость управляет только тем, что видят конечные пользователи.