Базы знаний и документация API

Два новых типа страниц: база знаний и документация API. Работают так же, как статус-страницы и страницы релизов: свой поддомен или собственный домен, оформление, аналитика.

База знаний

• Статьи, разделы, категории и теги. Раздел ведёт на свою первую статью, а на странице раздела показано его содержание.
• Черновики не мешают читателям: пока вы правите статью, на сайте остаётся опубликованная версия. Любую прошлую редакцию можно восстановить.
• Отложенная публикация: выберите дату и время, и в указанный момент выйдет именно та редакция, которую вы утвердили.
• Поиск находит слова по началу («вебх» найдёт «вебхуки») и в разных формах («установка» и «установить»).
• Читатели могут оценить, помогла ли им статья.
• Импорт с сайта: укажите адрес своей текущей документации, и сервис обойдёт сайт и разложит страницы по разделам, повторяя хлебные крошки и боковое меню. Вы выбираете, какие статьи перенести, и они появляются в базе черновиками. Таблицы, врезки и ссылки между статьями сохраняются.
• Импорт из архива с файлами AsciiDoc.
• Экспорт и импорт всей базы знаний одним архивом. Повторный импорт обновляет статьи, а не создаёт копии.

Документация API

• Спецификацию OpenAPI можно загрузить файлом, по ссылке или из репозитория в GitHub или GitLab. Изменения в репозитории подтягиваются автоматически, но к читателям попадают только после публикации.
• У каждой версии API свои руководства. Опубликованную версию можно откатить: по умолчанию прошлое состояние возвращается в черновик, чтобы вы проверили его перед повторной публикацией.
• Справочник сгруппирован по тегам и ресурсам. Группы сворачиваются, а раскрытые запоминаются. Есть фильтр по пути.
• Примеры тел запросов и ответов строятся по схеме. Ссылки $ref раскрываются на месте, JSON можно сворачивать.
• Выбор сервера с переменными: выбранный адрес сразу подставляется в примеры cURL и консоль.
• Консоль «Попробовать»: запрос уходит прямо из браузера читателя, наш сервер его не проксирует. Токен вводится один раз для каждой версии. Консоль включается отдельно, а методы, изменяющие данные, — ещё одним переключателем.

Общее для обоих типов страниц

• Приватные страницы со входом по паролю или через SAML SSO. Доступ к отдельным разделам и версиям API можно ограничить группами читателей. Читателями управляют в общем списке подписчиков.
• Подписка на обновления по email с подтверждением: на всё, на выбранные разделы или на выбранные версии API. В шапке появилась ссылка «Получать обновления», а внизу главной страницы — поле подписки.
• Markdown поддерживает врезки > [!NOTE], сворачиваемые блоки ::: details Заголовок и объединённые ячейки в таблицах.
• Для каждого типа — по три варианта оформления. Новые страницы по умолчанию получают оформление с боковой навигацией.
• Оформление и тему можно посмотреть в режиме предпросмотра до сохранения.
• Аналитика просмотров, поиска и оценок. Поисковые запросы читателей не сохраняются.

Тарифы для команды

• Тариф теперь оплачивается за команду, а не за каждую страницу. Тарифов три: Free, Standard и Premium.
• Тариф даёт премиум-слоты, которые можно распределить между любыми страницами команды: статус-страницами, страницами релизов и документацией.
• Плата списывается раз в день. Если средств на балансе не хватает, начинается трёхдневный льготный период; о нём приходит письмо.
• После окончания платного тарифа ничего не удаляется и не отключается: страницы продолжают работать, данные сверх лимитов остаются доступны для чтения. Приватная страница остаётся приватной.
• Чтобы подключить платный тариф, на балансе должна быть сумма, достаточная хотя бы для одного дня.
• Переход на Free работает как отмена подписки.

SSO для команды

• Вход в панель управления через SAML SSO (тариф Premium).
• Новые участники создаются автоматически при первом входе. Это можно отключить, и тогда войти смогут только уже добавленные участники.
• Можно выбрать роль, которую получат новые участники.
• Режим «только SSO» отключает вход по паролю для участников команды.
• Если SSO для команды не настроен или адрес команды изменился, вместо ошибки 404 открывается понятная страница с объяснением.

Публичный API

• Документация публичного API вынесена в отдельный документ на русском языке: statusmate.ru/api/schema/public/swagger-ui/. У каждого метода, параметра и поля есть описание.

Редактор

• Предпросмотр Markdown в редакторах инцидентов, работ и релизов. Для релиза видно, где будет отсечка «Читать далее».

Исправления

• В письме с подтверждением подписки на документацию больше не появляется служебный текст.
• На новых страницах релизов и документации уведомления подписчикам теперь отправляются сразу после создания страницы.