Автоматическая генерация документации для API

Написание документации для API, является неотъемлемой частью ее разработки. Очень часто возникает вопрос, каким образом лучше всего отобразить API. Существует масса инструментов, позволяющих писать документацию к API. Одним из основных способов является использование Markdown разметки. Но такой подход не всегда оптимален. В этой статье мы расскажем, как используя основанный на Markdown язык — API Blueprint, быстро написать документацию для API вашего сервиса и что для этого нужно сделать.

Итак, приступим. Blueprint — мощный язык описания API для веб-API, основанный на  Markdown и поддерживающий все его возможности. Создатели формата позиционируют его, как платформу для разработки или описания моделей и прототипов API.

Существует большое количество инструментов, позволяющих работать с API Blueprint. Весь список можно посмотреть здесь: https://apiblueprint.org/tools.html. Нас же интересует лишь один из них — Aglio.

aligo

Aglio — это инструмент для рендеринга API Blueprint с возможностью использования тем, макетов, и сохранением в статическую html-страницу. Давайте попробуем с ней поработать.

glaz

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

https://gist.github.com/AlxGolubev/90e828477cf15134b8c0

Установим Aglio

И запустим генератор

После запуска команды будет сформирован html-файл на основе написанной нами ранее документации.

У Aglio есть пять встроенных тем и два типа отображения — в два и три столбца. Ниже на скриншотах показан каждый из них со стандартной темой.

index-1

Список доступных для Aglio тем: streak, flatly, slate, cyborg. Для применения любой из них нужно воспользоваться опцией theme-variables

Важной особенностью является возможность использования своих стилей:

В плане удобства в работе с документацией можно запустить сервер для ее предварительного просмотра (http://localhost:3000):

Во время разработки документации мы советуем использовать Atom и плагины для работы с API Blueprint — api-blueprint-preview и language-api-blueprint

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

Будьте в курсе всех агро новостей

Ищи больше интересной информации в нашем TG-канале Подписаться

Заполните форму или свяжитесь
удобным для Вас способом

Контакты

г. Севастополь, ул. Руднева, д.41, 4 этаж технопарк ИТ-Крым +7 978 679-76-353 agro@crimeadigital.ru

Социальные сети

Нажимая на кнопку, вы даете согласие на обработку персональных данных и соглашаетесь c политикой конфиденциальности