Не уверен, что понял вопрос. Поэтому если отвечу не то, не обессудь)
Контроллер с его сигнатурой входа/выхода - это и есть интерфейс (контракт). А его реализация - сервис, где можно задействовать вот это вот всё. Так что здесь отображение кода не мешает ООП, а лишь гарантирует достоверность спецификации (хоть и делает ее более куцей). За кадром остались тесты, которые будут следить, чтобы контракт конкретной версии апи не поменялся. Но если документация использует не код, а дополнительные нотации - то тесты ее не защитят.
Большое спасибо! Наши фронты тоже поддержали эту мысль, что "сила в правде", и работать с актуальным апи без купюр лучше, чем с намарафеченной хнёй. Кажется, искусственное описание вместо отображения реальности - поворот не туда.
Не уверен, что понял вопрос. Поэтому если отвечу не то, не обессудь)
Контроллер с его сигнатурой входа/выхода - это и есть интерфейс (контракт). А его реализация - сервис, где можно задействовать вот это вот всё. Так что здесь отображение кода не мешает ООП, а лишь гарантирует достоверность спецификации (хоть и делает ее более куцей). За кадром остались тесты, которые будут следить, чтобы контракт конкретной версии апи не поменялся. Но если документация использует не код, а дополнительные нотации - то тесты ее не защитят.
Большое спасибо! Наши фронты тоже поддержали эту мысль, что "сила в правде", и работать с актуальным апи без купюр лучше, чем с намарафеченной хнёй. Кажется, искусственное описание вместо отображения реальности - поворот не туда.