Написание документации для API, является неотъемлемой частью ее разработки. Очень часто возникает вопрос, каким образом лучше всего отобразить API. Существует масса инструментов, позволяющих писать документацию к API. Одним из основных способов является использование Markdown разметки. Но такой подход не всегда оптимален. В этой статье мы расскажем, как используя основанный на Markdown язык — API Blueprint, быстро написать документацию для API вашего сервиса и что для этого нужно сделать.
Итак, приступим. Blueprint — мощный язык описания API для веб-API, основанный на Markdown и поддерживающий все его возможности. Создатели формата позиционируют его, как платформу для разработки или описания моделей и прототипов API.
Существует большое количество инструментов, позволяющих работать с API Blueprint. Весь список можно посмотреть здесь: https://apiblueprint.org/tools.html. Нас же интересует лишь один из них — Aglio.
Aglio — это инструмент для рендеринга API Blueprint с возможностью использования тем, макетов, и сохранением в статическую html-страницу. Давайте попробуем с ней поработать.
В наличии имеется небольшое приложение с API, которое позволяет получить список всех публикаций с информацией об авторе и документация к нашей API , написанная с использованием API Blueprint.
https://gist.github.com/AlxGolubev/90e828477cf15134b8c0
Установим Aglio
И запустим генератор
После запуска команды будет сформирован html-файл на основе написанной нами ранее документации.
У Aglio есть пять встроенных тем и два типа отображения — в два и три столбца. Ниже на скриншотах показан каждый из них со стандартной темой.
Список доступных для Aglio тем: streak, flatly, slate, cyborg. Для применения любой из них нужно воспользоваться опцией theme-variables
Важной особенностью является возможность использования своих стилей:
В плане удобства в работе с документацией можно запустить сервер для ее предварительного просмотра (http://localhost:3000):
Во время разработки документации мы советуем использовать Atom и плагины для работы с API Blueprint — api-blueprint-preview и language-api-blueprint
В интернете доступно множество сервисов, работающих с API Blueprint. Остается лишь выбрать тот, с которым вы хотите работать. Используя Aglio, вы получите бесплатный инструмент, с помощью которого создается приятная для глаз документация.
