Comments 9
Хороший пример, однозначно в копилку. Хотелось выразить отдельный + за само стремление делать код, а не спецификацию, на многих проектах в современном мире сваггер пишется в отрыве от кода и реализации и представляет собой больше набор обещаний, чем спецификацию реализованного сервиса.
Большое спасибо! Наши фронты тоже поддержали эту мысль, что "сила в правде", и работать с актуальным апи без купюр лучше, чем с намарафеченной хнёй. Кажется, искусственное описание вместо отображения реальности - поворот не туда.
А разве спецификация интерфейса не есть набор обещаний? А реализация - частный случай, выполняющий эти обещания?
Как по мне, так сам подход от кода в спецификации чреват проблемами с неотторгаемым интерфейсом от реализации, а потому стабы, моки, и бойлерплейт проходят мимо.
Не уверен, что понял вопрос. Поэтому если отвечу не то, не обессудь)
Контроллер с его сигнатурой входа/выхода - это и есть интерфейс (контракт). А его реализация - сервис, где можно задействовать вот это вот всё. Так что здесь отображение кода не мешает ООП, а лишь гарантирует достоверность спецификации (хоть и делает ее более куцей). За кадром остались тесты, которые будут следить, чтобы контракт конкретной версии апи не поменялся. Но если документация использует не код, а дополнительные нотации - то тесты ее не защитят.
Вам осталось сделать ещё один шаг и вы придёте к API platform :-)
Мое знакомство с этой штукой было примерно таким:
- Здравствуйте, желаете поговорить об апиплатформ? У нас контроллеры светятся от счастья, но на алтарь пойдут ваши модели, мы нашинкуем их дополнительными атрибутами, эти атрибуты с помощью других атрибутов перемешаем по группам (поверьте, это так удобно!), подсадим на круд-иглу, и политику доступов тоже заберем себе. Интересует?
- Спасибо, но мне бы просто генератор апи интерфейса (которым даже пользоваться будут в основном для экспорта в постмен/инсомнию).
Но теперь на их главной странице красуется ApiResource, без каких-либо обязательств. И я в растерянности) Возможно сам себе навертел это все на мозги.
Есть же Symfony 6.3: Mapping Request Data to Typed Objects зачем prugala/symfony-request-dto?
Всегда удивляли такие подходы реализацию контакта держать вместе с контрактом
Типичный Swagger без гмо