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

Мы Крым Диджитал

С 2015 года мы предоставляем полный цикл услуг мобильной и веб-разработки клиентам из различных отраслей и разных стран.

Подпишись
на наши новости

Контакты пресс-службы

+ 7 (926) 118-80-32

WhatsApp, Viber, Telegram

Давайте обсудим Ваш проект

или свяжитесь с нами по почте projects@crimeadigital.ru

Нажимая кнопку «Отправить», вы даете согласие на обработку персональных данных

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

Контакты

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

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

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

Крым Диджитал приняла участие в стратегической сессии

Руководители Крым Диджитал приняли участие в стратегической сессии, которая прошла на базе СевГУ 10 июня. Вместе с Правительством Севастополя, Институтом информационных технологий и управления в технических системах СевГУ и приглашенными ИТ-компаниями города обсудили перспективу развития системы высшего образования в Севастополе.Представители бизнеса, власти и образовательной системы выступали со своим видением будущих потребностей региона в кадрах, поднимали насущные вопросы обучения студентов, прохождения практики и дальнейшего трудоустройства. Крым Диджитал является амбассадором идеи образования и взращивания молодых кадров, развивает образовательные проекты и на протяжении 5 последних лет ведет активную работу в направлении поддержки и развития молодых специалистов ИТ-отрасли Крыма.

Руководители Крым Диджитал приняли участие в стратегической сессии, которая прошла на базе СевГУ 10 июня.

Вместе с Правительством Севастополя, Институтом информационных технологий и управления в технических системах СевГУ и приглашенными ИТ-компаниями города обсудили перспективу развития системы высшего образования в Севастополе.
Представители бизнеса, власти и образовательной системы выступали со своим видением будущих потребностей региона в кадрах, поднимали насущные вопросы обучения студентов, прохождения практики и дальнейшего трудоустройства.

Крым Диджитал является амбассадором идеи образования и взращивания молодых кадров, развивает образовательные проекты и на протяжении 5 последних лет ведет активную работу в направлении поддержки и развития молодых специалистов ИТ-отрасли Крыма.

Выпуск курса Software Testing

Мы поздравляем выпускников нашего первого в этом году курса Крым Диджитал Академии по Software Testing! Всего курс успешно завершили 13 человек. В течение 2 месяцев несмотря на теплую погоду и манящее море ребята ответственно посещали занятия 2 раза в неделю, делали домашние задания и проверочные работы. Трое начинающих специалистов теперь стажеры нашей компании. Следующий курс намечен на август. Не пропусти анонс записи!

Мы поздравляем выпускников нашего первого в этом году курса Крым Диджитал Академии по Software Testing!

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

Следующий курс намечен на август. Не пропусти анонс записи!

Лицензия на образовательную деятельность

В 2022 году мы получили лицензию на образовательную деятельность по программам дополнительного профессионального образования! Теперь мы можем обучать специалистов по направлениям Ruby on Rails, ReactJS и Software Testing и выдавать удостоверения о повышении квалификации государственного образца.
В 2022 году мы получили лицензию на образовательную деятельность по программам дополнительного профессионального образования! Теперь мы можем обучать специалистов по направлениям Ruby on Rails, ReactJS и Software Testing и выдавать удостоверения о повышении квалификации государственного образца.

Мы вошли в Реестр эффективно и социально значимых предприятий.

По результатам ежегодной финансово-экономической аналитики Межотраслевой рейтинговой компании Крым Диджитал включена в Реестр эффективных и социально значимых предприятий. По итогу аналитики, в рамках отрасли (ОКВЭД 62.01) и региона Крым, CDG вошло в 4% лучших компаний страны, с результатом – 92 балла!
По результатам ежегодной финансово-экономической аналитики Межотраслевой рейтинговой компании Крым Диджитал включена в Реестр эффективных и социально значимых предприятий. По итогу аналитики, в рамках отрасли (ОКВЭД 62.01) и региона Крым, CDG вошло в 4% лучших компаний страны, с результатом – 92 балла!