Обсудили в клубе тему, что реально можно автоматизировать на сервере, если у вас уже есть openapi-схема и наговорили на целый пост. А если схемы нет, то причины ниже, могут убедить вас или ваших коллег генерировать схему не по обработчикам, а наоборот.
Для начала нужны генераторы кода на базе openapi-схемы, таких в каждой экосистема по несколько штук как минимум. Как они помогают?
На базовом уровне генераторы просто создают DTO, которые вы сами парсите и валидируете вручную:
router.POST("/loginJSON", func(c *gin.Context) {
var json Login // Login сгенерирован
if err := c.ShouldBindJSON(&json); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
})
Это уже хорошая помощь от наличия спеки, но все еще очень много рукопашки и отсутствие контроля, того, что обработчики написаны правильно. Потому что одно дело сгенерировать структуры, а другое правильно (в соответствии со спекой openapi) их использовать в нужных местах. В общем что еще хотелось бы:
⁃ Валидацию запроса по схеме
⁃ Биндинг JSON → объект
⁃ Проверку ответа и статусов
⁃ Соответствие маршрутов и сигнатур контроллеров контракту
Только в этом случае, мы получим 100% пользу от наличия openapi схемы с максимальной автоматизацией всей рутины.
На практике же очень часто проверка ответа сводится к тестам, где JSON просто парсят и изучают его внутреннюю структуру вручную: сравнивают поля, типы, значения. В лучшем случае подключают валидацию по JSON Schema в тестах. Это по сути всё — ручная работа и проверки только на этапе выполнения тестов, без статических гарантий, подсказок редактора и без встроенного контроля на уровне фреймворка.
Полная генерация
Такое возможно только в случае наличия генераторов кода, которые глубоко интегрированы с фреймворком и умеют навешивать всю эту механику автоматически. Как минимум - иметь адаптер к конкретному фреймворку. К счастью, это есть плюс-минус во всех популярных экосистемах, но другой вопрос - знаете ли вы об этом и используете ли.
Давайте для примера возьмем Java и Spring Boot, где подобные задачи решаются давно и хорошо. В Spring Boot обычно используют OpenAPI Generator - он по спецификации генерирует интерфейсы контроллеров и модели (DTO). Вот пример интерфейса, который он генерирует:
public interface LoginApi {
@PostMapping("/login")
ResponseEntity<LoginResponse> login(@Valid @RequestBody LoginRequest request);
}
⁃ LoginRequest / LoginResponse — сгенерированные модели (с аннотациями валидации).
⁃ @RequestBody - Jackson сам парсит JSON → объект.
⁃ @Valid — проверка по аннотациям из схемы (400/422 уедут в хендлер ошибок).
И конкретная реализация
@RestController
class LoginController implements LoginApi {
@Override
public ResponseEntity<LoginResponse> login(LoginRequest req) {
var user = new User().id("u1").email(req.getEmail());
return ResponseEntity.ok(new LoginResponse().token("jwt...").user(user));
}
}
В итоге маршрут, сигнатура и типы подтягиваются из OpenAPI, модели тоже сгенерены. Мы пишем только логику внутри метода.
p.s. В ваших проектах используется полная генерация или частичная?
Ссылки: Телеграм | Youtube | VK