На прошлом проекте у команды стояла задача в короткие сроки создать API-спецификацию для ~70-ти эндпоинтов(contract-first разработка)
Проект на питоне, в качестве веб-фреймворка использовался fastapi, который сам создает openapi-спеку из эндпоинтов и отображает её в swagger, но работали по схеме contract-first разработки, а значит это бесполезная тулза. Я попробовал написать всё это руками(позже выяснилось что там в идеале должно быть суммарно ~13к строк), и сдался на втором роуте, потому что ну слишком геморно. Попробовал какие-то плагины для IDE, они позволяют эффективнее копипастить, но все равно не дают какого-то удобного графического интерфейса для быстрого написания. Генерация конфигов с параметрами тестирования в Postman - примерно тоже самое: там нельзя быстро ввести данные, потому что они все лежат в разных вкладках, между которыми нужно миллион раз переключиться.
В итоге было принято решение сначала написать эндпоинты со схемами на бэкенде(без кода самих эндпоинтов, просто аннотация типов), но я ушёл до того, как его реализовали. А вообще получается, что не существует нормального способа автоматизировать написание спецификации? Или это нормальная практика - писать эндпоинты(проще поддерживать + пишутся императивно) и собирать их в спеку при помощи какого-нибудь apispec?
P.S. И надо сабнуться на тгк: https://t.me/dmkjfss
Top comments (3)
В итоге я так и не понял что надо сделать :D
буквально ничего, это не гайд а наблюдение + какая-то чтоли просьба поделиться опытом. Я вот вообще не знаю как это сделать без костылей
и не гуглится блин ничего, а как это например на огромных проектах делают? отдельных технических писателей нанимают?
литералли:
"Не стоит вскрывать эту тему. Вы молодые, шутливые, вам все легко. Это не то. Это не Чикатило и даже не архивы спецслужб. Сюда лучше не лезть. Серьезно, любой из вас будет жалеть. Лучше закройте тему и забудьте, что тут писалось. Я вполне понимаю, что данным сообщением вызову дополнительный интерес, но хочу сразу предостеречь пытливых – стоп. Остальных просто не найдут."