Комментарии 7
Design API First-подход в первую очередь помогает создавать API более эффективно
Не соглашусь. Составление руками в Swagger Editor это издевательство. Зачем аналитикам вообще заходить на территорию даже не техлида, а мидла. REST и OpenAPI это базовая база, и регулярки тоже. Разве мидл-кодеру не достаточно списка действий и параметров и краткого описания их назначения с возможными значениями в свободной форме? Кодер готовит черновик, через автогенерацию собирается схема, аналитик через Swagger UI проверяет и при необходимости указывает что подправить.
Это зависит от процессов и представления команды, где находится источник правды. Если правдой считать код сервиса, то генерация схемы оттуда приемлема.
Мне все же видится, что schema-First подход более интересен, потому что позволяет развязать команды фронта, бека и тестирования и согласовать API максимально дёшево - всё же yaml поправить гораздо быстрее и дешевле, чем код бекенда. Также такой подход неплохо срабатывает в случае, когда API является внешним - проще создать схему (при её отсутствии) и нагенерить себе по ней клиентов, тестовых заглушек и чего угодно ещё
Но, как обычно, есть нюансы) Например, существующие инструменты генерации северного когда под .net не умеют в minimal API, odata и прочие штуки - генератор придётся писать самим. То же самое с клиентом - если используется библиотека, которая не поддерживается генератором, то попадаешь на разработку собственного инструмента
Поддержу, у нас аналитики просто пишут внятные описания api в свободной форме (обычно таблички в конфе) со списком входных/выходных параметров, действий и ошибок. И потом вместе с тестировщиками проверяют через swagger ui, что все сделано корректно.
Не, ну можно и на аналитиков повесить делать api через editor, но мне кажется, что более разумно посвятить это время на улучшение качества аналитики или проработку большего количества фич)
Отчасти согласна с теми, кто выступил против того, чтобы аналитики писали спецификацию openAPI. Не всем и не всегда это нужно / полезно / оправдано по ресурсам.
Но больше согласна с TerekhinSergey. Все очень сильно зависит от процессов в команде.
В той же заказной разработке без этого достаточно сложно - когда у тебя бэк делает один подрядчик, фронт второй - аналитик может быть вообще третий (бывало и такое). А сроки у всех как обычно горят.
В таком случае спецификация очень упрощает жизнь и позволяет стартануть работы в параллель - на согласованных контрактах, с примерами, на моках и тд.
А так да, тоже сталкивались с тем, что приходилось свой codegen писать, но его один раз написали и под все остальные проекты применяли.
По поводу того, что это издевательство - спорный момент. Тебе что хорошую документацию в конфлюенс написать, что спецификацию openAPI, по времени не сильно большая разница. Потому что тебе также нужно приложить примеры запросов / ответов, расписать каждый параметр. В Swagger Editor писать может и да, издевательство) но с применением любой IDE с нужными расширениями это уже не такое и издевательство - с генерацией шаблона, автодополнениями, быстрой навигацией по ссылкам на модели и тд.
А чтобы сгенерить хорошую спеку из кода разработка должна подзаморочиться и написать хорошие аннотации в коде по тому, что написано в конфлюенс - что не очень любят делать, по крайней мере на моем опыте обычно бывает именно так. И зачастую у тебя открыт SwaggerUI и документация в конфлюенс, чтобы понимать а что, где и как - не очень удобно так работать с API)
Согласна, аналитик руками дольше будет делать чем девелопер через IDE согласно базового описания.
Это занимает не так много времени, как вам кажется:)
Да, возможно у системного аналитика, который только начинает работать с OpenAPI (по хорошему еще и с Git) это может занять чуть больше времени, чем у более опытного в этом деле аналитика.
По факту - это не дольше, чем на каждый метод сформировать страницы в конфлюенс и описать все в виде текста и таблиц.
Мне кажется мы с вами говорим про разные подходы.
Проектирование спецификации OpenAPI может делаться аналитиком без особых проблем, в адекватные сроки для определенных целей - повторюсь, чтобы до этапа разработки согласовать контракты и в параллель пустить разработку (+ возможность использовать кодогенерацию для клиента, сервера, докуменnации, API тестов). Преимущества этого подхода подсвечены в статье.
В процессе согласования вносить правки в файл спецификации сильно быстрее и дешевле, чем в код бэкенда, как подсвечивали выше.
Если посмотреть любой курс по системному анализу, там будут темы по части проектирования REST API, т.е. системные аналитики умеют проектировать API (по хорошему) - вопрос в визуализации требований к API:
спецификация OpenAPI, которую можно удобно и полезно задействовать еще до появления кода разработчиков
или огромная текстовая таблица, которую надо превратить в код и только потом полезно задействовать, ну и вопрос - будут ли в этом коде понятные аннотации, чтобы сгенерированную документацию API отдать другим командам и в целом использовать как понятную, подробную документацию вашего API (по моему опыту - очень высока вероятность что нет, не будет).
Конечно, есть подходы где этим занимается разработка и в этом тоже есть свои плюсы и минусы.
Всем этим подходам есть место быть. Все зависит от процессов в компании, команде.
Проектирование спецификации OpenAPI