Aglio: Превращаем API Blueprint в элегантную документацию
Репозиторий давно не обновлялся
Последнее обновление было 7 лет назад.
Когда последний раз ваша API-документация вызывала у вас чувство гордости? Если ответ «никогда» или «очень давно», то знакомьтесь с Aglio — инструментом, который превращает скучные технические спецификации в визуально привлекательные и удобные для чтения HTML-документы.
Что такое Aglio?
Aglio — это рендерер для API Blueprint, формата документации API на основе Markdown. Главная фишка Aglio — возможность создавать статические HTML-страницы с документацией, которые можно разместить на любом веб-хостинге.
Проект существует с 2013 года и за это время собрал более 4700 звезд на GitHub, что говорит о его популярности среди разработчиков.
Почему Aglio — это круто?
1. Поддержка тем оформления
Aglio поставляется с несколькими встроенными темами:
- Default — классический двух- или трехколоночный вариант
- Streak — минималистичный дизайн
- Flatly — плоский дизайн с акцентами
- Slate — темная тема для комфортной работы ночью
- Cyborg — футуристичный стиль
Каждую тему можно дополнительно кастомизировать через LESS/CSS.
2. Гибкость использования
Aglio можно применять несколькими способами:
- Как консольную утилиту:
npm install -g aglio aglio -i input.apib -o output.html - Как Docker-контейнер
- Как библиотеку Node.js
3. Интерактивный режим разработки
Запустите локальный сервер с автоматической перезагрузкой:
aglio -i input.apib --server
Теперь при каждом изменении файла документация будет обновляться в реальном времени.
4. Поддержка включений
Можно разбивать документацию на части и включать их в основной файл:
<!-- include(partial.md) -->
Как это работает под капотом?
Aglio использует:
- Protagonist для быстрого парсинга API Blueprint
- Jade (теперь Pug) в качестве шаблонизатора
- LESS для стилей
Архитектура разделена на ядро и систему тем, что позволяет легко создавать собственные темы оформления.
Кому особенно пригодится Aglio?
- Разработчикам API, которые хотят автоматизировать создание документации
- Техническим писателям, работающим с API
- Командам, где важно поддерживать актуальную и красивую документацию
Aglio — это зрелый и проверенный инструмент для генерации API-документации. Хотя активная разработка сейчас замедлилась (автор ищет новых мейнтейнеров), проект остается отличным выбором для тех, кто работает с API Blueprint.
Попробуйте Aglio, если:
- Вы устали от скучной API-документации
- Хотите автоматизировать процесс генерации docs
- Цените возможность кастомизации внешнего вида
Примеры готовой документации:
