Skip to content

Latest commit

 

History

History
155 lines (110 loc) · 7.98 KB

README.ru.md

File metadata and controls

155 lines (110 loc) · 7.98 KB
Raw

@funboxteam/crafter

npm (scoped) Coverage Status

Crafter avatar

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

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

В Node.js

Парсинг файла:

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

CLI опции

  • -f, --format <format> — устанавливает выходной формат. Доступные форматы: json, yaml. По-умолчанию yaml.
  • -s, --sourcemap — добавляет карты кода в результат парсинга.
  • -d, --debug — включает режим, в котором некоторые исключения в BlueprintParser не перехватываются.
  • -l, --langserver — включает режим толерантного парсинга для Language Server.
  • -h, --help — отображает помощь.

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

npm test

Запуск в Docker

Для использования @funboxteam/crafter в Docker-контейнере нужно выполнить следующую команду в директории с вашей APIB-документацией:

docker run \
  --rm \
  -v $(pwd):/app \
  funbox/crafter -f json файл-с-документацией.apib

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

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

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

docker run \
  --rm \
  -v /$(pwd):/app/doc \
  funbox/crafter -f json doc/файл-с-документацией.apib

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

Почему API Blueprint

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

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

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

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

Sponsored by FunBox