Comments 11
В статье проповедуется contract first подход, и в тексте нет ни одного слова про OpenAPI/Swagger. Это структурированное описание API, которое могут интерпретировать программы, и, в свою очередь, генерировать серверный/клиентский код, рендерить документацию (с примерами и прочим), генерировать и исполнять интеграционные тесты и много чего еще. Совет автору и заинтересованным читателям: для проектирования API воспользуйтесь Postman или SwaggerHub или Stoplight Studio или, наконец, простым текстовым редактором с подсветкой yaml синтаксиса.
Спасибо за комментарий и совет!
Данный шаблон можно использовать для проектирования интеграций с использованием API с помощью REST паттерна, SOAP протокола, а также при интеграции через MQ и Kafka (с небольшой адаптацией). Проверяла на практике. Поэтому не стала писать именно про Swagger.
Используется именно такой формат документа, а не автогенерация из Swagger для удобства чтения и согласования с людьми в человеко-читаемом виде. А также документ в моей практике создается немного раньше разработки, то есть API еще нет и Swagger тоже.
Если говорить про асинхронные интеграции, то, конечно, без дополнительной документации не обойтись. Те же sequence диаграммы, например. Но недавно, вдохновившись успехом свагера, придумали AsyncAPI спецификацию. Несмотря на то, что спекая молодая, на нее уже делает ставку крупный энтерпрайз, например, конкуренты Альфа Банка.
SOAP API описывается в WSDL, и при наличии схемы API все преимущества использования доп. инструментария остаются прежними.
Причины, по которым важно структурированное описание API:
Поддерживать надо лишь один файл с схемой. Стоимость владения документацией ниже.
Структура описания API понятна сразу всем: клиентам, разработчикам, аналитику, который придет на замену вам.
Для клиента легко найти разницу с предыдущей версией API.
Автогенерация документации, если самой схемы недостаточно. В случае с REST просто открыть editor.swagger.io и вставить спеку.
Автогенерация клиента и сервера - стоимость внедрения и владения ниже. Это воплощенное в коде ТЗ, от которого уже никуда не деться на этапе разработки.
Не буду больше занудствовать в вашем посте, поднимающем важную тему. Если команда не готова использовать определенную спеку для описания API, то приведенного шаблона будет достаточно для документации.
Рад, что вместе раскрыли тему.
Конкретно эту интеграцию описали, ок; но даёт ли это разработчику понимание общей картины? Не почувствует ли он себя просто кодером, отделенным от бизнес- задачи? Поймёт ли разработчик место этого запроса-ответа в общей картине интеграционного взаимодействия? (решения - описание бизнес-контекста и назначения; диаграмма последовательности со всеми (этим и другими) интеграционными взаимодействия и)
Я намекаю на то, что погружение разработчика в пользовательский/бизнес контекст может дать свои бенефиты - разработчик может дать свои рекомендации. Да и вообще, что за средневековья специализация - разработчик, аналитик,... У вас что, разработчик не участвует в проработке задачи рядом с аналитиков? Тогда получите необходимость затрат на лишнюю коммуникацию
PS статья - норм!
Согласна с вашим комментарием, это шаблон помогает зафиксировать всё о чем договорились внутри команды. Просто некоторые команды сейчас в agile всё фиксируют на словах, в jira, в некоторых ситуациях это не удобно, поэтому появился такой минимальный шаблон
Конечно, разработчик участвует в проработке решения, сначала проводится грумминг, где показываем бизнес задачу, рассказываем а что нужно, то есть проектируем вместе исходя из бизнес контекста. Используем диаграмму поток данных, чтобы разработчик понимал окружение и задачу, тогда не будет ощущения кодера
Учитываем что требует бизнес сейчас и развитие, ведь иногда будушее наложит на реализацию текущую.
Также разработчик читает текущую Доку в процессе реализации, комментирует если не согласен и всё обсуждаем.
Недавно уволился из одной очень большой организации, где не только разработчик не участвует в проработке задачи, но и архитектор. Не, формально, конечно, они на PBR присутствуют, но когда доходит до тех. тонкостей - все резко становятся недоступны и перегружены. В итоге аналитик там додумывает ещё и за внешнюю систему, с которой коммуникации не налажены, либо у которой доработка стартует сильно позже и им сейчас её обсуждать неинтересно. К чему я клоню... Шаблон не столь важен, сколько процесс.
Зачем нужна новая интеграция бизнесу?
Вот кроме случая, когда команде разработке надо освоить деньги в виде интеграции, других вариантов на ум ничего не приходит, чтобы такой вопрос в принципе существовал. Т.е. рассматривать интеграцию как субъект - ну очень странно.
Наверное, у бизнеса есть выявленная (BA, тут - PO) потребность, и способ решения её - интеграция, ведь так?
Иногда, заказчик может прийти с требованием хочу показать людям сколько идти до ближайшено отделения почты, нужно эти данные забрать из Яндекс api. Начиная выяснять а зачем ему такая интеграция, можно прийти к тому, что дешевле с точки зрения разработки показать на карте ближайшие метро и это покроет потребность бизнеса, чем показывать время до метро
Мы на каких-то разных языках говорим.
В своём примере - "заказчик может прийти с требованием хочу показать людям сколько идти до ближайшено отделения почты" - это уже можно (с некоторой натяжкой, конечно, но) считать потребностью бизнеса. И следует (а не идёт в начале!) ваше решение - "эти данные забрать из Яндекс api".
А бизнес ваша реализация не интересует, бизнесу надо понимать дебет/кредит и время. Будет это интеграция, или прогнать 100500 человек по городу - ему без разницы.
Ещё раз: бизнесу не нужна никакая интеграция - ни новая, ни старая, ни ещё какая-либо. Ему нужно решение для своих целей. Интеграция - лишь вариант реализации
Удачный шаблон документации на API, который будут читать