Автоматическая генерация документации для 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

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

Прошел день карьеры в СевГУ

Резидент технопарка, компания Крым Диджитал, приняла участие в Дне Карьеры в СевГУ, который прошел 17 мая. Мероприятие длилось 3 часа. Компанией заинтересовались  более 35 студентов, которым была важна информация о прохождении практики, бесплатные курсы Академии и вакансии, не требующие опыта работы. Руководитель разработки компании выступил с презентацией и ответил на все вопросы, которые так волнуют студентов — как начать свою карьеру в ИТ? Есть ли возможность совмещать учебу с работой? Кем я смогу стать? Как понять, кем я хочу работать? И многие другие.

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

Мероприятие длилось 3 часа. Компанией заинтересовались  более 35 студентов, которым была важна информация о прохождении практики, бесплатные курсы Академии и вакансии, не требующие опыта работы.

Руководитель разработки компании выступил с презентацией и ответил на все вопросы, которые так волнуют студентов - как начать свою карьеру в ИТ?

Есть ли возможность совмещать учебу с работой?

Кем я смогу стать?

Как понять, кем я хочу работать?

И многие другие.

Завершен набор студентов на летнюю практику

Крым Диджитал завершила набор студентов на летнюю практику. В июле придут 14 человек. Это студенты второго и третьего курсов кафедр Программная инженерия, Информатика и вычислительная техника, Информационные системы и технологии и Управление в технических системах. Все ребята будут ходить в офис и будут заняты реальным проектом, который они должны реализовать до конца практики. Каждый выбрал для себя то направление, в котором хотел бы развиваться — front-end и back-end-разработка, дизайн. Руководить практикой будет Head of Engineering.
Крым Диджитал завершила набор студентов на летнюю практику. В июле придут 14 человек. Это студенты второго и третьего курсов кафедр Программная инженерия, Информатика и вычислительная техника, Информационные системы и технологии и Управление в технических системах. Все ребята будут ходить в офис и будут заняты реальным проектом, который они должны реализовать до конца практики. Каждый выбрал для себя то направление, в котором хотел бы развиваться - front-end и back-end-разработка, дизайн. Руководить практикой будет Head of Engineering.

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

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

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

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

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

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

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

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

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

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