В последние пару лет стал больше заниматься документацией. Написать поясняющий текст о том, как работает та или иная система — в целом, это достаточно просто. На...

C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures - RicardoNiepel/C4-PlantUML

А зачем я эт спрашивал? Да вот решил завезти Swagger в свой проектик и столкнулся с этим вопросом. (да, в контексте го, опрос был общий, для интереса)

С одной стороны генерить код по схему круто, ведь если это можно выразить схемой, то можно и кодом. Хотя тут же вопрос, а что там такого можно намудрить в рест-апи, что оно не выражается? Мне так-то вообще одних постов хватит аля json-rpc.

С другой стороны, а кто здесь главный? Я лучше знаю, как мне организовать мой код, и мне только и надо, что отдать пользователям схему для документации (генерация клиента тоже).

Тут можно прочитать, что кодген это плохо, но эт не так. Ведь если сгенерированный код только для потребления, то все круто. Берешь и используешь. Если же это код, в который нужно будет что-то дописывать, то это уже становится странно.

Поэтому остановлюсь схема по коду, чуть комментарии к ендпоинтам распухнут, но буду меньше париться из-за этого.

А вообще хочу такую красоту, как у Digitalocean сделать https://developers.digitalocean.com/documentation/v2/…