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

За чуть более десятилетнюю карьеру разработчика я успел опробовать несколько и пара из них прочно вошла в мои обязательные инструменты. Пока наиболее прочно в моей обойме осели Python, TDD и API-First. О последней хочу рассказать сейчас чуть больше, так как спустя пять лет применения думаю, что могу говорить о накопленном опыте.

Всё началось на заре моей карьеры разработчика в которую я перешёл из сферы системного администрирования. Проблема документации всегда стояла в IT достаточно остро. Но разработка это просто чёрная дыра в этом отношении. По сути, исходный код должен служить сам по себе документацией, но даже если ты прикладываешь максимальный объём усилий на поддержание его понятности, тебе всё равно нужны "костыли" в виде комментариев, докстрингов и отдельной документации. И часто сосредоточием документации становится README, хотя он по большому счёту не для этого.

Общеизвестно, самим разработчикам в том числе, что программисты не просто не любят писать документацию - они банально её не пишут. Причин много и желание побыстрее начать писать код, чтоб увидеть результат, не последняя. Про историю когда надо за месяц родить стабильный совершеннолетний и обкатанный в бою продукт, тоже забывать не будем.

Но реальность говорит нам, что какие бы не были причины - документация нужна. В основном я разрабатывал веб-сервисы и бекенды. Как правило система состояла из фронта и бека. Что вынуждало создавать между ними некий протокол для общения. Техническая история влекла за собой специфическое взаимодействие участвующих в ней специалистов, что в свою очередь приводило к формированию некоего документа описывающего API по которому взаимодействовали компоненты системы, разработчики, тестировщики и аналитики.

В какой-то момент описание API на "бумажке" по которому работает бэкенд стало настолько утомительным, что вынудило искать выход из сложившегося положения. Синхронизация "бумажки" и реальной ситуации в коде отнимало весьма заметные ресурсы. Вскоре после этого я узнал об OpenAPI, мне очень понравилась спецификация, результат описания API и самое главное SwaggerUI, который давал возможность не просто читать спецификацию наглядно, но и запускать вызовы эндпоинтов!

И где-то в этот момент я стал участвовать в проекте, который использовал веб-фреймворк FastAPI. Это было маленьким чудом, ты просто программировал на Python, а из твоих рук выходила достаточно понятная, доступная по URL спецификация, да ещё и с интерфейсом, который позволял взаимодействовать с твоим сервисом через вызовы API! Практически API-админка и всё это генерировалось на основе исходников реально работающего кода!

Казалось бы, что ещё нужно? Но на самом деле нужно. Спецификация всё ещё оставалась продуктом разработчика бекэнда. И ему приходилось так или иначе отслеживать её. Описывая компоненты спецификации исходники мгновенно раздувались, большое сложное описание чего-либо усложняло понимание кода просто своим наличием. При этом доступа ко всем возможностям самого OpenAPI не было или было усложнено. Разработчики не описывали кодом спецификацию больше минимального, что всё ещё оставляло вопросы для чатов и звонков. А аналитикам и часто фронтам было сложно ориентироваться в недосказанности спецификации. Но тем не менее это было огромным прорывом, хотя бы в том, что связывающий нас всех документ лежал в одном месте, у него был конкретный владелец и он максимально соответствовал коду бекенда.

После трёх лет работы, я пришёл к мысли, а почему бы не ... И выловил на просторах интернета такое понятие как API-First.

Я упёрся в ограничение для поста в Сетке, значит будет ещё пост.