Что делать, если никто не хочет документировать? Организация документирования микросервисов по минимуму

[Diaskhan]

Поддержка свагера хороша у строго типизированных языков таких как си шарп джава, у остальные платформы даже не знают чё такое сваггер и опенапи!

[Anrad]

Согласен -) Я с явой и работаю. Идея в том что надо в таком подходе использовать имеющиеся инструменты аннотации кода по максимуму.

[rinat_crone]

Позволю не согласиться. Мои рубисты (помидорами только не кидайте) использует связку grape + entity + swagger, что на выходе даёт open_api–документацию вообще без каких-либо дополнительных аннотаций в коде — куда уж проще.

[Anrad]

и это правильно ведь основная идея это использовать максимум возможностей в специфицировании от кода

[jreznot]

В Python есть опциональная типизация, на ней тоже можно делать OpenAPI

[Diaskhan]

к сожалению grape-entity для руби это костыль который скрывает нехватку статической типизации!. шел 2020 год а ейштеины придумывали очередной язык со статической типизацией, эх сколько было сломано копей об динамическую типизацию!

[JordanoBruno]

Движение в сторону статитеческой типизации оправдано тем, что это позволяет снизить число ошибок. А причины такие:
1) Много низкоквалифицированных разработчиков из-за дороговизны опытных и трудности с наймом.
2) Большая ротация по проектам. Человек, не знакомый с проектом, может легко допустить ошибку в предполагаемом типе и ему труднее понять, где и какие типы.
3) Статическая типизация очень хорошо заходит в современных IDE, которые делают проверку ошибок на лету, упрощают рефакторинг и так далее.

[Losted]

Проблема, с которой мы столкнулись при попытке использовать code-first подход к сваггеру — это не удобство обсуждения и согласования планируемых изменений между разными частями организации. По итогу делаем сначала сваггер (спека), а код ее реализует.

[Anrad]

Полностью согласен. И в конкретном случае все внешние API все же идут через солюшин архитектора. Но код-вперед активно используется для рестов фронтенда (а у нас все фулстеки) и для бэкенд микросервисов, которые никто особенно не согласуют. И представленное решение является попыткой наведения хоть какого-то порядка

[visirok]

А общую структуру сервисов (например, разбиение на группы) и их зависимости вы как документируете?

[Anrad]

В конкретном, выше описанном случае, разбиение сервисов на группы не практикуется.
Зависимости пока решили не документировать. Рассматривали две опции. 1) Описывать в том же Readme.md отдельной секцией. 2) Контролировать зависимости автоматически через мониторинг сетевой активности и авто репортинг с размещением в отдельный репозиторий для контроля изменений. И для Кубернета и для OpenShift есть такие средства. Я более склоняюсь к авто контролю зависимостей.

[visirok]

Я более склоняюсь к авто контролю зависимостей.

Признаться, в случак реальной логики я сомневаюсь, что это будет работать. Например — сервис А спрашивает сервис Б и в зависимости от параметра х далее спрашивает иногда В, иногда Г а иногда подождёт и переспросит Б. А сервис Б…
Другими словами, общие Workflows надо описывать в каких-то центральных моделях. И лучше не текстом, а UML.

[Anrad]

Yes. Of course. I agree. But in case of nobody want to document it and nobody ready to change, in my view, the best option to use network monitoring or a distribute trace capability like Spring Cloud Sleuth.