Skip to content

Latest commit

 

History

History
153 lines (105 loc) · 9.66 KB

README.ru.md

File metadata and controls

153 lines (105 loc) · 9.66 KB
Raw

API Blueprint Language Server

В этом репозитории находится плагин для VS Code, который добавляет поддержку Language Server для формата API Blueprint. Он базируется на протоколе Language Server Protocol и позволяет разработчикам более удобно работать с документацией API Blueprint в редакторах кода и IDE.

Мотивация

Хотя формат API Blueprint и основан на Markdown, их семантика сильно отличается. Там, где в Markdown описаны секции, параграфы и заголовки, в API Blueprint они означают различные структуры данных и кастомные типы.

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

Поддерживаемые возможности

  • Подсветка синтаксиса.
  • Диагностические сообщения об ошибках парсинга документации.
  • Переход к определению структур данных и Resource Prototypes.
  • Хлебные крошки.
  • Автодополнение.

Структура пакета

├── client            // Language Client
    └── extension.js  // Language Client entry point
├── package.json      // The extension manifest.
└── server            // Language Server
    └── server.js     // Language Server entry point

Установка в VS Code

Сборка расширения из исходников

  • Выполнить npx @vscode/vsce package в корневой директории.
  • Установить запакованное расширение по инструкции.
  • Полученный пакет передать для установки другим заинтересованным лицам.

Загрузка из магазина расширений

Расширение пока что недоступно в маркетплейсе.

Установка в IDE от JetBrains (WebStorm, PhpStorm и пр.)

Добавление поддержки Language Server Protocol

Для работы с LS необходимо установить плагин LSP Support.

Последняя версия плагина (1.6.1) работает крайне не стабильно, а разработка приостановлена на неопределённый срок, поэтому рекомендуется установить версию 1.6.0.

Установка:

  1. Скачать архив LSP.zip.
  2. Перейти в раздел с плагинами в настройках IDE (Preferences → Plugins).
  3. Нажать на иконку шестерёнки и выбрать пункт «Install Plugin from Disk…».
  4. Указать путь до файла LSP.zip.

После успешной установки файл LSP.zip можно удалить.

Настройка плагина LSP Support

Настройка плагина производится по пути Preferences → Languages & Frameworks → Language Server Protocol → Server Definitions.

Необходимо установить следующие настройки:

  1. В выпадающем меню выбрать Executable.
  2. В поле Extension указать apib.
  3. В поле Path указать полный путь до исполняемого файла node.
  4. В поле Args первым аргументом указать полный путь до файла server/server.js, а вторым, через пробел, добавить текст --stdio. Пример: /full/path/to/vscode-apib-ls/server/server.js --stdio.

Так же возможен вариант настройки с глобальной установкой LS в виде исполняемого файла.

Для этого необходимо в директории проекта выполнить команду npm link, после чего убедиться в том, что из терминала доступен вызов команды apibserver.

Затем, в настройках плагина, в поле Path изменить значение на apibserver, а в поле Args на --stdio.

Важно. После любых изменений настроек плагина лучше перезагрузить IDE.

Работа с многофайловой документацией

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

По умолчанию, плагин пытается найти файл doc.apib в корне проекта и использовать его в качестве корня. Если такой файл не найден, то документация считается однофайловой.

Если в проекте в качестве корневого используется файл отличный от doc.apib, то об этом можно сообщить плагину с помощью настройки:

File → Preferences → Settings → Extensions → API Blueprint → Entry Point

Если по каким-то причинам в файле не подсвечиваются ошибки, то первое, что надо проверить — подключается ли данный файл прямо или опосредованно в корень проекта.

Разработка расширения

Запуск для разработки в VS Code

  • Выполнить npm install в корневой директории.
  • Открыть VS Code.
  • Переключиться в Debug viewlet.
  • Запустить Launch Client.
  • Открыть проект с APIB документацией или отдельный APIB-файл.
  • Запустить Attach to Server.

Вместо отдельных шагов Launch Client и Attach to Server можно использовать команду Client + Server, но тогда APIB-файл нужно открывать достаточно быстро, иначе команда Attach to Server завершится с ошибкой.

Отладка

Для отладки сервера можно использовать точки останова и отладочный вывод.

Для отладочного вывода можно использовать функцию connection.console.log. При этом результаты вывода необходимо искать в окне Extension Development Host в панели Output - API Blueprint Language Server.

Сборка публичной версии

Перед публикацией исходники расширения собираются в бандлы (отдельный бандл для client, отдельный бандл для server) с помощью esbuild.

Чтобы собрать минифицированную версию бандла (аналогично той, которая будет опубликована), нужно выполнить npm run esbuild-min. Чтобы собрать читаемую версию бандла (например, для отладки сборки), нужно выполнить npm run esbuild.

Кроме этого, можно проверить, какие файлы попадут в опубликованную версию. Для этого нужно выполнить команду npx @vscode/vsce ls. Если пакет @vscode/vsce уже установлен глобально, то достаточно выполнить vsce ls.

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

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

Sponsored by FunBox