В сегодняшней статье я покажу вам, как создать документ OpenAPI, содержащий определения API, на этапе тестирования.
Прежде чем мы начнем, вы можете найти весь код здесь.
Что мы строим?
Интеграционный тест, который генерирует документ OpenAPI, содержащий определения для простого REST API, документированного с использованием библиотеки Springdoc.
Почему мы строим?
Чтобы лучше отслеживать изменения нашего API и автоматизировать процесс, чтобы исключить ручное вмешательство разработчика для обновления документации вручную, поскольку это подвержено ошибкам.
Как мы строим?
Зависимости Maven
Добавьте зависимость Springdoc в свой pom.xml:
Остальные версии здесь.
Настройте зависимость spring-boot-starter-test для использования JUnit5:
Определить API
Бизнес-логика, стоящая за этим, не имеет значения, поскольку нас больше интересует ее правильное документирование с использованием аннотаций Springdoc.
Обратите внимание на @Tag, @Operation, @ApiResponsesи @Parameterаннотации, используемые для документирования API. Все они являются частью пакета io.swagger.v3.oas.annotations.
Напишите интеграционный тест
Примечание. Убедитесь, что вы импортируете правильные тестовые аннотации из пакета org.junit.jupiter.api.
Цель этого интеграционного теста — запустить контекст Spring и запросить конечную точку /v3/api-docs.yaml, чтобы получить сгенерированные определения API и записать их в отдельный файл.
Я использую MockMvc для выполнения запроса. О стратегиях интеграционного тестирования можно прочитать здесь и здесь.
Настройка подключаемого модуля Maven Surefire
Я использую плагин Maven Surefire для запуска модульных и интеграционных тестов с
mvn clean install или mvn test команды.
Запустите тесты
Для запуска тестов мы используем команды mvn clean install или mvn test. После завершения этапа тестирования мы можем найти новый файл с именем openapi.yaml, который был создан нашим интеграционным тестом в папке src/main/resources/apidocs:
Примечание: если вы хотите сгенерировать файл в другом месте, вам нужно изменить путь в тесте интеграции.
Если вы откроете файл, то увидите что-то вроде этого:
Заключение
Как всегда, имейте в виду, что этот подход может соответствовать или не соответствовать контексту или потребностям вашего проекта, и я не могу сказать, что нет другого способа сделать это по-другому или лучше. Я очень надеюсь, что вам понравилось, и вы получили удовольствие от чтения.
Берегите себя и помните, что вы можете найти код здесь.
