Так-то оно так. Вот только в проекте, в котором сейчас работаю принято наоборот : код->Swagger->дока. А я не могу сильно повлиять на внутренние процесса. Вот и ищу, как можно доку по API улучшить без доступа к коду.
Кажется для синхронизации разработчиков можно дописывать спеку вручную в
https://editor.swagger.io и эти спеки без реализации как-то в сорс-контроле хранить.
А если нужна хорошая дока для внешних пользователей, то видимо следует строить ее отдельно рядом со swagger-докой. И там заниматься контентной работой - описывать примеры и юз-кейсы - это мне все время в свагере жмёт.