В Qmino (компания, создавшая Miredot) мы написали сотни REST API. Мы проектируем и редизайнируем до тех пор, пока наши API не станут приятными в использовании.
Документация — это пользовательский интерфейс API.
Это то, во что мы твердо верим. Единственный способ показать хороший API — предоставить разработчикам красивую и правильную документацию.
Вот почему мы очень тщательно относимся к документации. Мы даже позволили отсутствию Javadoc привести к сбою наших сборок, а проверка кода включает проверку документации. Кроме того, мы заставляем Miredot завершать сборку, если она обнаруживает что-то не так с документами REST API.
Миредо
Несколько лет назад мы действительно не могли найти хороший инструмент для документирования REST API для Java. Мы хотели что-то, что брало бы любые существующие артефакты, такие как Javadoc, исходный код Java, аннотации и так далее. Что-то, что понимает используемые нами фреймворки, такие как jax-rs, spring и jackson, и превращает это во что-то красивое. То, что любят использовать потребители наших API.
Это именно то, к чему мы постоянно стремимся с Miredot. И пока мы очень гордимся результатом!