Боли псто( Кто-нибудь научился готовить swagger без боли?
Я даже не имею ввиду генерацию сервера или клиента (пару раз пытался, на код без кровавых слез смотреть нельзя), а тупо генерацию спеки по серверному коду, которую можно импортнуть к примеру в postman и отдать фронтам. Третий раз я это пытаюсь сделать, сначала в одном проекте на python но было давно детали не помнб помню что был гемморой. Затем проект на node, nestjs, было +/- ок но весь код моделей и контроллеров пришлось обвешать аннотациями. Сейчас бэкенд на go, и я почти обрадовался что go-swagger позволяет спеку отдельным package оформлять не засирая код, но бляха муха писать yaml в комментариях - то еще удовольствие и главное пока спеку не проверишь в swagger ui гарантировать что там все +/- ок невозможно.
Отдельная боль это авторизация, еще ни разу не удалось сделать такую спеку по которой postman поймет автоматом на каких методах какая авторизация, но это я уже на postman грешу.
Вобщем уже посещвет мысль не выпендриваться, забить и писать спеку руками если она очень нужна, но думаю может все таки есть тайное знание в природе?)
Я пишу спеку руками и очень это пропагандирую. Во-первых, это единая точка правды для всех команд: фронта, бэка, мобильных клиентов. Её никто не может сломать случайно, только намеренно (при генерации из кода бэка - можно сломать, изменив сигнатуру метода контроллера, и никто этого не заметит, пока баг не уедет в интеграционное или e2e тестирование).
Во-вторых, если хорошо аннотировать ручки - то это готовая документация. Доп. аннотации можно добавить потом, можно их менять, если пришёл фидбэк типа "что-то непонятно", не трогая при этом код.
В-третьих, можно использовать кодгенерацию не только для клиентов, но и для бэкенда.
В-четвёртых, при старте работы над новой фичой достаточно описать все ручки в спеке - и клиенты могут начинать работать, stub-серверов есть в ассортименте.
В-пятых, спеку можно бесплатно использовать для acceptance-тестирования бэкенда.
