Oops... your message was not sent

Your message has been successfully sent

тематические истории, основанные на опыте компании JetRuby
API

Автоматическая генерация документации для 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, вы получите бесплатный инструмент, с помощью которого создается приятная для глаз документация.

department
Статью подготовил
Отдел веб-разработки
Профессиональная разработка сайтов и приложений на стороне сервера и клиента. Проектирование дизайна, верстка страниц и техническое обслуживание реализованных проектов.
New Articles