В компании «ТехВилл» команда тестирования решила связать Swagger-документацию и API-автотесты напрямую. Олег Малышев, один из лидеров стека тестирования, описал процесс, в котором Swagger перестаёт быть статическим документом и становится источником правды для тестов.

Типичная проблема: QA вручную собирают URL, пишут JSON и парсят ответы, а Swagger живёт отдельно. В ТехВилл пошли другим путём. На примере сервиса Cohorts они построили пайплайн: Swagger-файл → OpenAPI Generator + Mustache-шаблоны → generated Java-клиент и модели → JUnit + RestAssured тесты → Swagger Coverage → отчёт покрытия → LLM-skills для генерации недостающих тестов.

OpenAPI Generator берёт спецификацию и создаёт методы API и DTO-модели. Например, endpoint POST /api/v1/cohort с operationId createCohort превращается в метод cohortsDefaultApi().createCohort(), а модель CreateCohortsRq — в Java-класс с builder-методами. Чтобы generated-код лучше вписывался в тестовый фреймворк, используются кастомные Mustache-шаблоны (api.mustache и pojo.mustache). Они определяют, как выглядят generated-методы: public CreateCohortOper createCohort() {... } с возможностью execute(), executeAs(), body() и так далее.

Автотесты не содержат ручных URL и JSON — всё берётся из контракта.

После генерации тесты используют не ручные given().get(), а вызовы generated-клиента. Swagger Coverage вычисляет, какие endpoint’ы и коды ответов покрыты тестами, и формирует отчёт в HTML и JSON. Эти отчёты подаются LLM (через Cursor или Claude Code) с навыками, которые генерируют недостающие тесты. Такой подход обеспечивает синхронизацию тестов с контрактом: если в Swagger добавили новое поле, оно автоматически появляется в Java-моделях, и тесты можно сразу обновить.

Использование OpenAPI Generator с Mustache-шаблонами даёт контроль над генерацией без ручного кодирования DTO. В ТехВилл считают, что это снижает расхождение между документацией и тестами, а также упрощает поддержку при изменении API. Подход уже применяется на сервисе Cohorts и, вероятно, будет масштабирован на другие микросервисы.