Всем привет! В данной статье хотел бы рассмотреть инструменты документирования в принципиально разных подходах в разработке REST API, а именно для CodeFirst - инструменты SpringRestDocs (а также его надстройку SpringAutoRestDocs) и для ApiFirst - инструменты экосистемы Swagger(Open-Api). Дисклеймер: В подробности холивара на тему что же лучше CodeFirst или ApiFirst я вдаваться не будут, а постараюсь продемонстрировать возможную практику документации в обоих вариантах. Как уже описывали в статье про SpringRestDocs это инструмент достаточно широкого использования, позволяющий генерировать различную документацию (аскедок, хтмл и т.д.) на основе тестов. Пожалуй один из немногих недостатков этого инструмента, является его многословность в тестах, а именно - необходимо описывать каждый параметр, каждое поле и т.д. В свою очередь тесы в SpringAutoRestDocs, используя JSR и Spring аннотации, а также Javadoc, становятся более коротким и немногословными. SpringAutoRestDocs это надстройка над SpringRestDocs, которая ставит своей целью уменьшение написания кода и документации. Основное преимущество этого иструмента - является меньшее количество написанной документации и большая связаность с рабочим кодом. Некоторые из фичей инструмента: Автоматическое документирования полей запроса и ответа, хедеров и параметров запроса с использованием Jackson, а также описательной части на основе Javadocs Автоматическое документирование опциональности и ограничения полей по спецификации JSR-303 Возможность кастомизации итоговых снипеттов Подробнее можно почитать в официальной документации. Для демонстрации возьмем классический Swagger PetStore (с небольшой модернизацией, подробно можно посмотреть спеку в репозитории) и имплементируем несколько методов контроллера (addPet, deletePet, getPetById). В статье будет приведен пример на основе одного метода getPetById Контроллер: Репозиторий является обычным листом с несколькими методами доступа. Базовые настройки для тестовой автодокументации: Для начала нам необходимо определить базовый класс для всех тестов, который опишет основные правила нашей автоматической документации. Основное что нам понадобится, это сконфигурированный MockMvc (более подробно можно посмотреть в репозитории): WebApplicationContext получаем от @SpringBootTest prepareJackson(objectMapper, new TypeMapping()) позволяет настроить ResultHandler, который подготовит наши pojo для библиотеки документирования withDefaults(curlRequest(), httpRequest(), и т.д.) набор сниппетов, которые будут сгенерированы commonDocumentation() описывает директорию, куда в build папке разместятся сгенерированные сниппеты, а также препроцессинг ответа контроллера. Непосредственно сам тест: Пример теста более подробно можно посмотреть в репозитории. Здесь приведен стандартный MockMvc тест, с ожидаемым статусом и ожидаемым телом ответа. Итого на выходе: Набор снипеттов с "главным" сниппетом под названием auto-section.adoc (который содержит информацию из всех остальных, указанных в настройках MockMVC) из которых позже можно собрать общий index.adoc для всех методов API. Готовая структура сниппетов: Готовые сниппеты документы можно посмотреть в репозитории: сниппеты, html сгенеренный на основе сниппетов. Также при настройках библиотеки мы можем изменять шаблоны либо добавлять свои сниппеты и SprinAutoRestDocs их распознает и воспроизведет ту функциональность, что вам нужна. Дока кастомизации сниппетов, констрейнтов. Функционал кастомизации в SpringAutoRestDocs базируется на таковом же в SpringRestDocs. На примере аскедок шаблонов - в ресурсы вашего проекта в папку org/springframework/restdocs/templates/asciidoctor необходимо добавить нужный вам сниппет без приставки default-Список дефолтных аскедок сниппетов. На примере ограничений - в ресурсы вашего проекта в папку org/springframework/restdocs/constraints необходимо добавить файл DefaultConstraintDescriptions.properties с переопределенным списком ограничений Список дефолтных ограничений и их сообщения. К примеру русификация шапок сниппетов и описание ограничений: Как уже описывалось во множестве статей (пример1, пример2) swagger - это open-source проект, включающий OpenApi Specification и широкий набор инструментов для описания, визуализации и документирования REST api. Swagger состоит из двух основных частей - это OpenApi Specification и Swagger Tools. OpenApi Specification - это спецификация описывающая процесс создания REST контракта для более простого процесса разработки и внедрения API. Спецификация может быть описана в формате YAML и JSON. Описание базового синтаксиса, а также более подробную информацию можно изучить по ссылке. Swagger Tools - это инструменты визуализации, документации и генерации клиентно-серверной части REST api. Состоят из трех основных блоков: Swagger Editor(браузерный эдитор, для более удобного написания контракта с поддержкой валидации ситаксиса),  Swagger UI(рендер спецификации в качестве интерактивной документации API), Swagger Codegen(генератор серверно-клиентной части, а также некоторых типов документаций) Ниже мы рассмотрим мульти-модульный проект со следущей структурой: библиотека со свагер генератором (swagger-library), стартер с swagger-ui(swagger-webjar-ui-starter), приложение которое имплементирует классы библиотеки(spring-auto-rest-docs). Для демонстрации возможностей Swagger возьмем классический Swagger PetStore из примера SpringAutoRestDocs выше. Настройки build.gradle для модуля библиотеки: Для реализации генерации server stub и документации на основе Swagger контракта используем OpenApi Generator. В модуле используется gradle плюс gradle plugin OpenApi Generator. Сам плагин дает возможность генерить как серверно-клиентную часть, так и различные форматы документации. Более подробно можно посмотреть в ссылке на репозиторий. Основная таска для генерации библиотеки и ее настройки: generatorName - в качестве основы для генерации серверной части используем  Spring (проперти для настройки генератора spring) dateLibrary - позволяет изменить шаблон используемых в генерации библиотек работы с датой (joda, JSR-310 и т.д.) также можно изменять глобальные проперти генератора, не зависящие от конкретной реализации Незабываем выполнять генерацию кода до компиляции проекта: Копируем спеки в ресурсы, чтобы была позже возможность отобразить UI прямо из спек: При необходимости также можно сгенерить Asciidoc или Html2. Swagger-ui стартер: Стартер добавляет в регистр ресурсов спеки с определенными в дефолтными настройками и webjar swagger-ui с измененным путем до дефолтного контракта. Rest-docs API: В самом приложении достаточно имплементировать сгенерированный интерфейс и переопределить настройки UI стартера: Итого на выходе: Server stub - готовая библиотека с сущностями и интерфейсом для реализации серверной части API. Swagger UI - с помощью которого мы получаем наглядную визуализацию API и возможность направлять запросы прямо из UI: Также примеры Asciidoc или Html2 из самого swagger контракта: Что дает SpringAutoRestDocs: Возможность хранить документацию как в проекте (к примеру в форме собранного index.html из множества сниппетов), так и в любом другом удобном месте. Документация и модель данных всегда синхронизирована с кодом, так как документация генерируется на основе "зеленых" тестов контроллера. Возможность кастомизации сниппетов и ограничений. Что дает Swagger: Единый артефакт на всех этапах разработки. Документация и модель данных всегда синхронизирована с кодом, так как код генерируется на основе контракта. Возможность использовать UI, в котором будет вся та же информация, что в контракте с возьможностью направлять запросы.      Какой бы вы не выбрали путь разработки, инструменты выше практически всегда позволят вам содержать актуальную документацию, тесно связанную с рабочим кодом. Java developer