Системе уже 20 лет. И код кишит старыми описаниями.

удали все, и скажи "дорогу молодым" =)

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

То есть все описания хранятся в этой отдельной папке для сваггера?

Не уверена, что я сама смогу такое реализовать технически, но поговорю с разрабами — может они знают.

Да, я изначально планировал делать так, чтобы ее структура повторяла код, чтобы девам было проще найти доки, если это необходимо

Технически можно реализовать проще - натравить swagger ui на индекс файл и сервить его куда-то

@gold_mister_gold А если меняется код — например, появляется новый метод или в модельку добавляется один параметр — эти изменения автоматом попадают в эту отдельную папку для swagger?

Я как-то потратил два дня чтобы один наш сервис обложить описаниями с помощью drf-yasg. Получилось, конечно, хорошо, но поддерживать так себе такое. Там можно описать прямо рядом с нужными ручками апи все детали параметров и примеры и описания полей и ошибок. И он что-то умеет из коробки вынимать, но на деле сильно тюнить надо самому если хочется чтобы было хорошо.

Это немного противоречит чему-то на внутреннем уровне что ты вроде сервис пишешь, а на деле там же в коде описываешь какие-то штуки о том как это должно отображаться. Я уверен, что ваши разрабы как раз этого боятся (что им в таком же духе всё придётся делать) потому что для них наверное впиливать новые ручки интереснее чем описывать их (к тому же вы говорите что проект старый, так что может они ещё и не хотят туда лезть лишний раз)

В идеале конечно лучше когда спека идёт до реализации, но в мир который так боится вотерфола к такому наверное не готов

А вообще есть утилиты, которые по спеке генерируют код сервиса. И такое обычно лучше всего выполняет требования соответствия кода описанию. Но к сожалению тут тоже надо чтобы в команде была экспертиза, так как в более-менее сложном домене такие инструменты всё равно придётся под себя докручивать

Нет, вручную добавляем

Разрабы не хотят туда лезть лишний раз, а я устала каждый раз сравнивать два swagger-файла: свой с обновленными описаниями и разрабский со старыми описаниями, но новыми методами и параметрами. Вот и мучаюсь

Давите на них

Унижайте

Надсмехайтесь над их методами работы

+1))

😂😂😂 Я попробую!

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

Часто помогает просто поговорить, скорее всего там они не против в целом, но есть какая-то мелкая глупость которая мешает им вас пустить к себе в бардак

Думаю, что ещё дело в том, что проекту 20 лет, и в коде черт голову сломит.

ну так и скажите, в коде бардак