Skip to content

Latest commit

 

History

History
264 lines (192 loc) · 17.7 KB

README.ru.md

File metadata and controls

264 lines (192 loc) · 17.7 KB
Raw

@funboxteam/blueprinter

npm (scoped) Coverage Status

Blueprinter avatar

Blueprinter — это рендерер API Blueprint. Он получает на вход AST API в формате Elements и генерирует HTML-страницу с документацией.

Мотивация

Стандарт API Blueprint разрабатывает компания Apiary, ей принадлежит официальный парсер Drafter. Параллельно энтузиасты разрабатывают другие инструменты для работы с API Blueprint, в том числе и рендерилки.

Долгое время стандартным набором в компании для работы с APIB было сочетание парсера Drafter и рендерера aglio. Через Drafter и aglio удобно работать с документацией, но их функционала нам стало недостаточно: во время работы над проектами часто требуются новые фичи и исправление багов.

Blueprinter появился как замена aglio, поскольку код в aglio трудно читать и поддерживать, а используемые технологии устарели. Автор aglio забросил проект и не принимает новые PR. Drafter также был заменён собственным парсером Crafter.

Наши реализации написаны на JavaScript, их легко развивать и поддерживать силами разработчиков фронтенда без привлечения других специалистов.

Преимущества

  • Современный дизайн. С поддержкой тёмной темы!
  • Поиск по документации. Можно быстро переходить к группам, ресурсам и экшенам, находя их по части URL или заголовкам.
  • Версия для печати. В режиме печати со страницы удаляется всё лишнее и остаётся только нужный контент в адаптированном виде.
  • Выбор опций One Of. В нашей реализации можно выбирать разные опции внутри One Of и динамически формировать пример тела ответа.
  • Страница ручного поиска. Функциональности поисковой строки может быть недостаточно, если нужно найти часть описания или отдельно взятый атрибут. На странице ручного поиска можно воспользоваться стандартным браузерным поиском по тексту.
  • Отображение предупреждений и ошибок парсинга. Предупреждения, связанные с парсингом документации, отображаются в виде специального уведомления. Ошибка парсинга, не позволяющая отобразить весь документ, выводится в виде отдельной страницы с детальной информацией.

Установка

npm install --save @funboxteam/blueprinter

Использование

Добавить команды в package.json:

{
  "scripts": {
    "dev": "blueprinter -i doc.apib -s -p 3000",
    "doc": "blueprinter -i doc.apib -o index.html"
  }
}

Скрипт dev запустит на порту 3000 live-сервер с отрендеренной документацией и будет следить за изменениями исходных файлов. Скрипт doc сгенерирует конечный HTML-файл с документацией и сохранит его как index.html.

CLI опции

  • -i, --input <file> — задаёт исходный APIB-файл, который нужно отрендерить.
  • -o, --output <file> — задаёт название конечного HTML-файла.
  • -s, --server — активирует режим live-сервера.
  • -h, --host <host> — задаёт адрес локального live-сервера. По умолчанию 127.0.0.1.
  • -p, --port <port> — задаёт порт локального live-сервера. По умолчанию 3000.
  • --strict — включает «строгий» режим парсинга, в котором любое предупреждение приведёт к ошибке сборки.
  • --css <file> — позволяет указать путь к кастомному CSS-файлу, стили из которого будут подключены на странице. Любые проблемы совместимости актуальной версии Blueprinter и кастомного CSS-файла остаются на совести разработчика файла.
  • --locale <locale> — задаёт язык интерфейса конечного HTML. По умолчанию en. Возможные варианты: en, ru.
  • --favicon <file> — позволяет указать путь к кастомной фавиконке. Фавиконка применяется только в режиме сборки и не учитывается при запуске dev-сервера. Разрешены только файлы в формате PNG.

Использование через Docker

Blueprinter можно запустить в виде Docker-контейнера, выполнив следующую команду в директории с APIB-документацией:

docker run \
  --rm \
  -v $(pwd):/app \
  funbox/blueprinter -i doc.apib -o index.html

Здесь опция --rm автоматически удалит созданный контейнер после завершения рендера документации, а опция -v примонтирует текущую хост-директорию с документацией в некоторую директорию в контейнере.

По умолчанию рабочей директорией образа задана директория /app, поэтому удобнее всего смонтировать хост-директорию непосредственно в /app, как это сделано в примере выше. В таком случае в качестве параметра -i можно передать просто название файла файл-с-документацией.apib, иначе придётся указывать путь к APIB-файлу относительно созданного в контейнере пути.

Использование через Docker в режиме dev-сервера

Чтобы запустить Blueprinter в контейнере в режиме dev-сервера, нужно выполнить следующую команду в директории с вашей APIB-документацией:

docker run \
  --rm \
  -v $(pwd):/app \
  -p 3000:3000 \
  funbox/blueprinter -i doc.apib -s -p 3000

Если в параметре -p для Blueprinter передаётся порт, отличный от 3000, нужно также открыть доступ к этому порту в контейнере из хост-системы, указав в параметрах Docker опцию -p port:port.

Внимание! При завершении процесса dev-сервера через Ctrl/Cmd + C процесс с контейнером отсоединяется (переводится в detached), но контейнер при этом остаётся запущенным.

Чтобы остановить контейнер, необходимо использовать команды:

docker ps # смотрим ID запущенного контейнера
docker stop <container> # останавливаем контейнер с указанным ID

Использование Docker-контейнера в Windows

При запуске контейнера в Windows нужно добавлять слэш (/) перед вызовом pwd:

docker run \
  --rm \
  -v /$(pwd):/app \
  funbox/blueprinter -i doc.apib -o index.html

Кроме того, примонтированная директория может быть пустой. В таком случае необходимо убедиться, что в настройках Docker Desktop for Windows, в разделе Shared Drives включен шаринг нужного диска (стоит галка). Если диск не расшарен, необходимо отметить его как shared, применить изменения и перезапустить Docker Desktop.

Функциональные возможности

Поиск групп, ресурсов и экшенов

HTML-страница с отрендеренной документацией содержит поле для поиска различных ресурсов. Автоматически установить фокус на поле поиска можно клавишей /.

Поиск производится по следующим сущностям:

  • Заголовки и описания групп, ресурсов и экшенов.
  • href экшенов.

При этом результаты поиска выводятся в следующем порядке:

  1. Совпадения по href экшенов.
  2. Совпадения по заголовкам групп, ресурсов и экшенов.
  3. Совпадения по описаниям групп, ресурсов и экшенов.

Кроме ввода обычного поискового запроса, например empl или сотр, также доступны некоторые модификаторы (фильтры) поиска. В общем виде запрос с модификатором имеет вид modType:modValue query, где query — нужный поисковый запрос. В частности, доступны фильтры по типу ресурса и по HTTP-методу:

  • Фильтр по типу — type:action query. Возможные значения: type:group query, type:resource query, type:action query.
  • Фильтр по методу — method:METHOD query, где METHOD — нужный HTTP-метод (GET, POST, DELETE и так далее). Метод можно вводить как в нижнем регистре, так и в верхнем.

Таким образом, чтобы вывести только GET-запросы, у которых href содержит employ, можно ввести в поисковой строке:

method:get employ

Чтобы модификатор применился, поисковый запрос должен начинаться с modType. Это значит, что если необходимо найти в документации фразу method:get - пример фильтра, то можно использовать первым символом запроса пробел ( method:get - пример фильтра). Модификатор при этом не применится, пробел учитываться не будет, а поиск будет выполняться именно по фразе method:get - пример фильтра.

Поиск через Ctrl/Cmd + F

APIB-документация содержит много разнородных сущностей, поэтому поле поиска может не помочь в ряде случаев, когда нужно искать по значению атрибута или по URI-параметру. Для ручного поиска добавлена страница с последовательным выводом всего контента документации, попасть на которую можно через кнопку-пиктограмму справа от поля поиска.

На этой странице все группы, ресурсы, запросы и ответы выводятся последовательно, также раскрыты все атрибуты в секциях Attributes. Таким образом, можно искать по документации, используя браузерные средства, например через комбинацию клавиш Ctrl + F.

Сохранение в PDF

PDF-версия документации оптимизирована для удобного просмотра. Содержание в начале документа упрощает навигацию к выбранному разделу. Блок с описанием JSON-схемы скрыт в версии для печати.

Для сохранения документации в формате PDF средствами браузера Chrome нужно выполнить следующие действия:

  • перейти на страницу ручного поиска, попасть на которую можно через кнопку-пиктограмму справа от поля поиска;
  • в меню браузера выбрать опцию печати страницы;
  • в открывшемся диалоге просмотра печати страницы выбрать в настройках принтера «Сохранить как PDF» и вид раскладки «Книжная»;
  • сохранить документацию с указанными настройками.

Работа с проектом для разработки

Установка зависимостей

npm install

Запуск проекта

Запуск проекта в режиме разработки:

npm start

Проект запустится по адресу http://localhost:8080.

Сборка проекта

Для локальной сборки проекта:

npm run build

Поддержка интернационализации

В этом проекте добавлена поддержка нескольких языков для текстов интерфейса (на данный момент, поддерживаются русский и английский языки).

Чтобы отметить текст, который должен быть переведён, нужно применить макросы t или Trans из пакета @lingui/macro. Чтобы перевод появился в интерфейсе, нужно выполнить следующее:

  • запустить npm run extract, чтобы обновить JSON-файлы с каталогами переводов (см. src/locales/{locale}/messages);
  • внести в каталоги отсутствующий перевод новых текстов;
  • запустить npm run compile, чтобы скомпилировать каталоги в JavaScript-файлы;
  • закоммитить внесённые изменения.

Почему API Blueprint

В нашей компании разрабатывается большое количество JSON API. Их необходимо описывать и согласовывать, отслеживать изменения и показывать документацию большому кругу лиц, поэтому возникла необходимость в удобном формате и средствах для работы с документацией.

Исторически в компании происходил выбор между API Blueprint и Swagger. Мы выбрали API Blueprint по двум причинам. Во-первых, исходный код документации, описанной с помощью API Blueprint, проще воспринимается человеком. Во-вторых, на момент исследования в Swagger не хватало ряда важных возможностей, например One Of.

Благодарности

Клёвый логотип для проекта нарисовал Игорь Гарибальди.

Sponsored by FunBox