Проект

Инструмент для создания и тестирования RESTful API на основе стандартных Java-комментариев.

Зачем создавать собственный инструмент?

• Люди, страдающие обсессивно-компульсивным расстройством, не могут смириться с навязчивыми аннотациями Swagger в коде. Они предпочитают более чистый код.
• Использование аннотаций требует определённых затрат на обучение.
• После попытки использовать Apidoc стало ясно, что затраты на обучение не уменьшились. Нужно изучать дополнительные теги аннотаций, а также вручную вносить информацию о нужных интерфейсах с помощью этих специальных тегов. Ощущения, что работа по написанию документации стала легче, нет.
• Есть проекты, которые генерируют документацию на основе стандартных комментариев Java, но некоторые из них не поддерживают:
  • параметры сущности;
  • переменные типа;
  • многомодульность;
  • сторонние зависимости;
  • интеграцию микросервисной документации. Некоторые из них содержат слишком много ошибок, их пользовательский интерфейс недостаточно дружелюбен, а способы использования слишком сложны (требуется зависимость от Maven-плагина и громоздкой конфигурации), и даже логическая обработка вызывает проблемы.
• Если бы API-документ одновременно интегрировал функции тестирования класса PostMan, это было бы идеально. Не нужно было бы постоянно переключаться между API-документацией и инструментами тестирования вроде PostMan или RestClient. Разве это не удобно?

Особенности (подробнее см. здесь)

• Предоставляет smalldoc-spring-boot-starter и стандартную конфигурацию, позволяя быстро интегрировать инструменты документации в проект spring-boot.
• Генерирует документацию на основе исходного кода Java, стандартных комментариев и тегов, без вмешательства в код, обеспечивая чистоту кода.
• Включает множество проверок и утверждений для комментариев, гарантируя соблюдение разработчиками правил комментирования и стандартов.
• Имеет мощный синтаксис конфигурации параметров, удовлетворяя различные требования разработчиков к отображению параметров.
• Поддерживает автоматическое распознавание сложных параметров, таких как параметры сущности, поля типа, поля коллекции и связанные сущности.
• Позволяет настраивать игнорирование анализа структуры данных указанных пакетов или указанных типов параметров.
• Можно настроить анализ имён классов, поддерживая регулярные выражения.
• Поддерживает многомодульные проекты и сторонние зависимости.
• Интегрируется с документацией микросервисов.
• Совместимо с UNIX-системами.
• Может выводить предполагаемые значения примеров параметров интерфейса.
• Содержит функцию тестирования API.
• Предлагает дружественный пользовательский интерфейс по умолчанию и поддерживает автономное создание документов.
• Предоставляет RESTFul API для документации, поддерживающий реализацию настраиваемого пользовательского интерфейса.