Это жизненный вопрос)

А можешь рассказать как и где именно?

могу, но сейчас пока нет времени.. постараюсь попозже чего-то сформулировать

Хочу сразу изучить процесс документирования.
В целом, было бы здорово понимать полноценно как работает, и сферу применения. Хотелось бы перестать использовать условные таблички с описанием API и перейти на swagger, он же как раз для этих целей и существует

ну он точно удобнее табличек

у нас сваггер, как посткод идёт

т.е. автоматом собирается по коду, я в него уже, как в источник смотрю

На разных проектах использовали. Кейсы:
- аналитик передает сваггер разработке как требования
- разрабы генерят сваггер из кода
- разрабы генерят из сваггера аналитика код

Получается точнее и информативнее табличек, но ощутимо больше времени жрет у аналитика

Сваггер используем постоянно.
Он не заменит вам табличек в документации.

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

Альтернатива написанию таблички - если аналитик сам генерирует YAML и передаёт в разработку. Это требует скилла и опыта.

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

Минут - частые срачи между отделами при интеграции, когда дока расходится со сваггером.

Тут речь про yaml?

Сваггер не может быть информативнее табличек, т.к. в таблички можно добавить поведенческое описание, ссылки, много разных примеров, источники данных

Может, конечно. Все это можно добавить и в сваггер

На сваггер будут смотреть внешние клиенты (путь даже это будут другие внутренние команды).
Лишнего туда сильно не напихнаешь. например, не укажешь почему было сделано именно так, или на основании какого требования (хотя последнее наверное можно).
Зачем вам сваггер с тонной документации к нему? Как вы будете её смотреть? Кто её будет смотреть?

У нас есть в компании аналитики, которые работают интеграционные без табличек вообще.
Они просто собирают YAML и передают в разработку, те автогенерят код на основании полученного файла и добавляют логику и обращения к источникам данных.
Вуоля, метод в API готов.

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

Лично мне сваггер нравится тем, что можно самостоятельно проверить, сделал ли разработчик всё по спеке или опять велосипед собрал.

#таргетолог #разборы #консультации

Ребята, привет👋

Меня зовут Иван)

Привлекаю подписчиков в блог и заявки в IT компанию через таргет Instagram и Facebook.

Провожу сейчас бесплатные консультации и разборы рекламных кампаний. Также даю рекомендации по улучшению всей воронки.

Если для кого то актуален этот вопрос, напишите в ЛС, подскажу и помогу 😊

Но важно!
Если делать и табличку и YAML, то это будет двойная работа. Так лучше не делать.
Либо делать YAML + доку по логике без описания контракта.
Либо делать только доку, а сваггер оставлять как артефакт разработчика.

Короче, попроси, чтобы на ОДНОМ сервисе, который собираются сделать в рамках твоей задачи прикрутили сваггер и вывели UI.
Пока делаешь на нём аналитику, попробуй создать для апи YAML-файл, а потом передавай его в разработку (с автогенерацией кода или без - лучше с автогенерацией, т.к. сразу проверяются ошибки сборки).
Желательно, чтобы апишка была не сложной.
Вот таким образом сразу во всём разберёшься.
Можно использовать для проверки MS Visual Code + плагин Open API
И https://editor.swagger.io/