Comments 7
Судя по всему у вас разработчики которые зачем-то борются со Swagger'ом, вместо того чтобы дружить с ним. Ну а вообще тут есть как плюсы, так и минусы
При генерации спецификации OpenAPI из кода, это снижает трудозатраты на ее описание, это может быть критически важно на молодом проекте, в котором API очень быстро развивается и часто устаревает
Если разработчики сильно уйдут в полиморфизм и наследование в своих DTO, то сгенерированная спецификация выйдет довольно сложная к восприятию, и по ней не получится сгенерировать клиент на половине доступных языков программирования
Ну и забыли упомянуть один из основных плюсов OpenAPI - современные фреймворки позволяют развернуть на бэкенде веб-сервис с веб-интерфейсом его OpenAPI-спецификации (не важно сгенерированной или заранее прописанной из файла), и за счет этого получить песочницу по тестированию этого бэкенда, без необходимости для разработчиков собственноручно писать веб-интерфейс, а для тестировщиков/аналитиков - использовать Postman или Curl.
Привет! Спасибо за комментарий! Ответ от Елизаветы: Насчет трудозатрат — спорный момент, тут все зависит от уровня квалификации аналитика и его опыта работы с OpenAPI. На первых этапах, действительно, казалось, что внедрение этого процесса увеличивает сроки реализации задачи. Но со временем, когда команда набила руку, всё стало идти гораздо быстрее, и по времени это практически не отличается от написания спецификаций вручную в документации.
Что касается полиморфизма и наследования — пока такой проблемы не возникало. Спасибо за предупреждение, будем внимательнее к этому моменту.
А вот про генерацию клиентов — отличное дополнение! Мы как раз используем эту функциональность для создания клиентов и тестирования наших бэкэнд-сервисов, что реально упрощает жизнь.
В общем, вы в точку попали с комментариями. Спасибо, что поделились!
А где вы храните спеки по задачам и общую спеку?
Привет!) Ответ от автора:
В задачах спецификацию не храним, очень сложно потом синхронизировать ее с общей частью, на моем опыте никто из аналитиков после реализации задачи этого не делал (забывали, не хотели, нет времени и еще 1001 причина). Вместо этого вся документация ведется в базе знаний. В таске описываем верхнеуровнево пункты, которые нужно сделать (создать сущность1, реализовать метод2), а для более детальной информации прикрепляем ссылки на страницы в доке и выделяем цветом дельту, которую нужно реализовать.
Что касается задач на интеграцию: для клиентов (в нашем случае фронтов) или смежных команд достаточно при таком подходе отдать swagger, там вся исчерпывающая информация, которая им необходима. Для разработки бека к swagger еще прикладываем описание внутренней логики, которая также хранится в базе знаний
Самих баз знаний 2: swagger (хранится в git) и wiki
а в гит кто пушит и мержит, разруливает конфликты?
Мы просто в процессе перехода на Спек-фирст и есть какие-то пробуксовки)
Привет!) Ответ от автора:
Аналитики создают отдельную ветку, дорабатывают спецификацию и отправляют на ревью разработчикам. Дальше мяч на их стороне: идет этап ревью, при необходимости отправляют на доработку. Все изменения мержат уже разработчики после окончательного согласования, иногда в этой же ветке проводят реализацию внутренней логики метода, когда она описана и освободились ресурсы
Очень здорово, что переходите на новую модель работы со спецификацией! Процесс непростой, это правда, мы его обкатывали не один месяц, но оно того стоит
Как OpenAPI повлиял на наш системный дизайн