Crafter — это парсер документации API Blueprint, написанный на JavaScript. Библиотека является заменой Drafter и включает в себя некоторые дополнительные возможности.
Drafter реализован на языке программирования C++. Код библиотеки достаточно сложный и грязный, содержит много багов и легаси. Разобраться, как работает тот или иной блок, очень сложно. Если исправление багов разработчики принимают охотно, то при попытке добавить новую фичу можно потратить много времени на обсуждение, а в итоге фичу так и не примут.
В нашей компании практически нет проектов на C++, поэтому разработчиков, которые могут поддерживать Drafter, очень мало, при этом необходимость в новых фичах возникает регулярно.
Так появилась собственная версия на JavaScript, которая устраняет недостатки оригинала, легко поддерживается JS-разработчиками и реализует все необходимые возможности.
По сравнению с Drafter, эта библиотека может предложить следующие возможности:
- Модульность. Теперь можно разбить общий файл на части и подключать отдельные APIB файлы друг в друга, что облегчает работу с документацией.
- Прототипы ресурсов (Resource Prototypes). Позволяют задать общие ответы для разных ресурсов в одном месте и переиспользовать их во всей документации.
- Использование массивов в GET-параметрах.
- Описание типов с помощью JSON Schema. Полезно в случае сложных типов, которые затруднительно описать в виде MSON.
- Атрибуты строковых параметров, которые задают ожидаемую длину или регулярное выражение, которому строка должна соответствовать.
- Поддержка описания не-HTTP взаимодействия (например, WebSocket) с помощью секций Message.
Более подробную информацию о работе библиотеки можно найти в документах из docs.
Глобально:
npm install -g @funboxteam/crafter
Локально в проект:
npm install --save @funboxteam/crafter
Парсинг файла:
const crafter = require('@funboxteam/crafter');
const apibFile = 'doc.apib';
const ast = (await crafter.parseFile(apibFile))[0].toRefract();
Парсинг APIB-документа в виде строки:
const crafter = require('@funboxteam/crafter');
const source = '# My API\n\n## List users [GET /users]\n\n+ Response 200';
const ast = (await crafter.parse(source))[0].toRefract();
Для парсинга из файла документации doc.apib
требуется выполнить следующую
команду:
crafter [options] doc.apib
-f, --format <format>
— устанавливает выходной формат. Доступные форматы:json
,yaml
. По-умолчаниюyaml
.-s, --sourcemap
— добавляет карты кода в результат парсинга.-d, --debug
— включает режим, в котором некоторые исключения в BlueprintParser не перехватываются.-l, --langserver
— включает режим толерантного парсинга для Language Server.-h, --help
— отображает помощь.
npm test
Для использования @funboxteam/crafter в Docker-контейнере нужно выполнить следующую команду в директории с вашей APIB-документацией:
docker run \
--rm \
-v $(pwd):/app \
funbox/crafter -f json файл-с-документацией.apib
По умолчанию рабочей директорией образа задана директория /app
, поэтому
удобнее всего смонтировать хост-директорию непосредственно в /app
. Тогда в
качестве параметра можно передать просто название файла
файл-с-документацией.apib
.
При запуске контейнера в Windows нужно добавлять слеш (/
) перед вызовом pwd
.
Команда будет выглядеть так:
docker run \
--rm \
-v /$(pwd):/app/doc \
funbox/crafter -f json doc/файл-с-документацией.apib
Кроме того, примонтированная директория может быть пустой. Если это так,
необходимо убедиться, что в настройках Docker Desktop for Windows, в разделе
Shared Drives включен шаринг нужного диска (стоит галка). Если диск не расшарен,
необходимо отметить его как shared
, применить изменения и перезапустить Docker
Desktop.
В нашей компании разрабатывается большое количество JSON API. Их необходимо описывать и согласовывать, отслеживать изменения и показывать документацию большому кругу лиц, поэтому возникла необходимость в удобном формате и средствах для работы с документацией.
Исторически в компании происходил выбор между
API Blueprint и Swagger. Мы
выбрали API Blueprint по двум причинам. Во-первых, исходный код документации,
описанной с помощью API Blueprint, проще воспринимается человеком. Во-вторых, на
момент исследования в Swagger не хватало ряда важных возможностей, например One Of
.
Клёвый логотип для проекта нарисовал Игорь Гарибальди.