Markdown в IntelliJ IDEA как отдельный вид искусства. Рисуем диаграммы и вызываем bash команды

Spring разработчики часто пишут документацию и README/HELP файлы к своим приложениям. Часто это делается в Markdown файлах. Markdown плагин в IntelliJ IDEA распознает файлы, предоставляет специальный редактор с подсветкой, автокомплитом и форматированием, а также дает визуальное отображение в панели предварительного просмотра в реальном времени. Кроме стандартной функциональности в IntelliJ IDEA есть пару уникальных фич, которые команда Spring АйО хотела бы выделить особенно.

Отображение Mermaid и PlantUML диаграмм

Что насчет отображения Mermaid и PlantUML диаграмм? Для поддержки их отображения потребуется установить соответствующие плагины. Достаточно объявить блок кода в markdown файле с указанием plantuml или mermaid языка, и во вкладке с визуальным отображением вы увидите полноценную диаграмму.

Отображение PlantUML и Mermaid диаграмм в markdown файле

Кстати, отображение Mermaid диаграмм поддерживает еще и GitHub markdown preview. К сожалению, поддержки для PlantUML в GitHub нет.

Выполнение команд терминала

При клонировании проекта обычно имеется файл README.md с инструкциями и командами для запуска приложения, настройки среды и т. д. IntelliJ IDEA обнаруживает эти команды и предоставляет значки для их запуска. Следующие блоки кода будут выполняемыми в IDEA:

Выполняемыми команды из markdown файла

Поскольку IDEA Ultimate с поддержкой http client становится все дальше и дальше от российских разработчиков (раз, два и три), отдельно стоит рассмотреть выполнение cURL команд через markdown файл. Также, как и в http файлах вы можете описать GET, POST, DELETE и другие HTTP запросы и выполнять их из markdown файла для проверки работоспособности ваших эндпоинтов.

Выполнение cURL команд из markdown файла

Не только bash скрипты

Но если функциональности bash не достаточно (или у вас аллергия на bash), то можно воспользоваться полноценным языком таким как kotlin, java, groovy, и т.д. Достаточно из markdown вызвать заранее заготовленные скрипты на kotlin/groovy scripts или JBANG (если кто-то помнит что это такое).

Давайте опять попробуем импортозаместить IntelliJ http client через один файл kotlin script.

1. Создаем .kts файл. Тут есть интересная особенность. Чтобы заработал запуск файла и поддерживались все автодополнения, добавления зависимостей и т.д., файл должен оканчиваться на .main.kts.

2. Добавим в наш скрипт библиотеку RestAssured, через специальную конструкцию:

   @file:DependsOn("io.rest-assured:rest-assured:5.4.0")

3. Напишем простенький тест с проверкой и выводом результата:

   import io.restassured.RestAssured.*
   import org.hamcrest.Matchers.*
   
   baseURI = "http://localhost:8089/rest"
   
   get("/owners?city=Madison&sort=firstName")
     .then().log().body(true)
     .statusCode(200)
     .body("content[0].firstName", equalTo("David"))
     .body("content[1].firstName", equalTo("Maria"))
     .body("content[2].firstName", equalTo("Peter"))

   Мы уже можем запустить этот скрипт вызвав команду Run .main.kts из контекстного меню этого файла.

4. Добавим вызов этого скрипта через утилиту kotlinc в markdown файл:

   kotlinc -script ./test/rest.main.kts

   Преимущества такого подхода перед http client очевидны, у нас есть все возможности языка и настоящий фреймворк для тестирования.

   

   Запуск kotlin script из markdown файла

Про другие возможности редактирования и просмотра markdown файлов вы можете прочитать в документации.

Присоединяйтесь к русскоязычному сообществу разработчиков на Spring Boot в телеграм - Spring АйО, чтобы быть в курсе последних новостей из мира разработки на Spring Boot и всего, что с ним связано.

Ждем всех, присоединяйтесь!