Ко мне тут недавно пришли и говорят: Напиши пост, зачем аналитику нужно описывать REST API в виде свагера. И я такой: а действительно, для чего?

Для тех, кто не в теме: OpenAPI specification/swagger - спецификация для описания REST API. С ее помощью можно описать каждую часть API (например, запросы и ответы, способы авторизации и тд) и представить это в интерактивном виде

На своем первом проекте я был местным экспертом по свагеру😄. Вместе с лидом мы проектировали огромнейшую апиху для оркестратора, после чего я все переносил в свагер. В итоге, получился огромный файл на несколько тыщ строк, который описывал абсолютно все нюансы.

А на текущем проекте все описание у нас в виде табличек. Почему? Потому что: ➖у ребят-джунов не было нужных компетенций. Я попробовал попросить, чтобы перенесли в swagger то, что уже было в виде табличек, но это заняло кучу времени и результат вышел не тот, что требовался. Можно было потратить время, чтобы научить, но на тот момент все сроки горели, и было не до этого; ➖API состоял всего из 4 методов с несложной логикой, и у него был всего один потребитель.

Обдумав свой опыт, я бы выделил следующие преимущества и недостатки описания в swagger: ✅ единый формат описания. В случае, если в компании принято использовать swagger, не будет зоопарка из разных описаний в разных командах. Все унифицировано и понятно; ✅ все в одном месте. Swagger позволяет описать почти все аспекты (кроме внутренней логики) API: методы и их эндпойнты, схемы и примеры запросов и ответов, возможные ошибки и их состав, способы авторизации и тд; ✅ интерактивное представление. Любой желающий может на живом примере посмотреть, как выглядит тот или иной метод, а если прикрутить работающий хост, то и повызывать его; ✅возможность для разработчика сгенерировать модель данных на основе готового свагера;

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

Итого, что бы я порекомендовал аналитикам: 🔹изучите синтаксис и опишите пару апишек чисто для себя. Бесполезным это точно не будет, и возможно позволит вам в голове уложить все аспекты rest api. У меня до сих пор при проектировании апих в голове то, как это будет выглядеть в свагере; 🔹если у вас несколько потребителей или сложная по атрибутному составу апиха, лучше используйте OpenAPI. Будет проще и вам, и потребителям; 🔹если единственным потребителем вашей API является ваша же система, модель данных не сложная, а свободных рук нет, не тратьте время, опишите все в виде таблички. Можете потом попросить разработку выгрузить swagger, сгенерированный по коду, и прикрепить его к страничке (но тогда придется его сопровождать).