С документацией к API есть две крайности, и обе плохие: написанная руками врёт через полгода, сгенерированная целиком стирает всё осмысленное, что в неё написали.

Я перестал выбирать между ними и поделил файл: структура принадлежит коду и синхронизируется без спроса, проза принадлежит человеку и не трогается никогда. Заодно оказалось, что документацию можно проверять как golden-файл, и что проверить нельзя прозу, а вот её отсутствие можно.

Лень — двигатель прогресса. Я очень ленив, поэтому прогресс должен был выйти впечатляющим. Спойлер: он и вышел, но с ленью что-то пошло не так.

Началось с того, что я предложил взять go-playground/validator — и услышал, что рефлексия нас замедлит. Бенчмарки показали единицы микросекунд на структуру: примерно столько же, сколько json.Unmarshal того же тела, и на три порядка меньше похода в базу двумя строками ниже. Решение всё равно осталось прежним.

Поэтому я убрал рантайм целиком: разбор запроса и валидация генерируются из тегов структуры на этапе сборки. Опечатка в теге стала ошибкой генерации, а не пропущенной проверкой. Транспорт и вовсе оказался ни при чём.

Ниже — как это выглядит, чего генератор делать отказывается и чем я за это заплатил.