Comments 2
Написана на ноде (JS), это минус.
Смысл описывать protobuf сторонней спецификацией, если можно его описать напрямую proto файлами?
Так же в openapi есть сложные сценарии с anyOf, oneOf и т.п. Есть сомнения что тут это как-то учтено.
По моему мнению это лишняя сущность ведущая к усложнению.
Согласен, nodejs уже не в тренде, но свою задачу он выполняет за вполне приемлемое время с ожидаемым результатом.
Смысл описывать protobuf сторонней спецификацией, если можно его описать напрямую proto файлами?
Здесь, скорее всего, можно переиспользовать модели, которые созданы для REST, чтобы не дублировать их в proto.
Так же в openapi есть сложные сценарии с anyOf, oneOf и т.п. Есть сомнения что тут это как-то учтено.
это есть и, на мой взгляд удобно реализовано через union-типы: https://typespec.io/docs/getting-started/typespec-for-openapi-dev/#polymorphism-using-anyof-and-oneof-oas3
По моему мнению это лишняя сущность ведущая к усложнению.
Это, наверное, зависит от масштаба API. На небольших проектах, где ямлик итоговой спецификации содержит до 1000 строк, то с ним можно как-то работать напрямую. Но когда у меня в спецификации больше 250 методов, больше 600 DTO, есть закрытая и открытая части спецификации, все это в разрезе 10 сервисов, то приходится повышать уровень абстракции, чтобы этим всем нормально управлять.
Сейчас мы используем собственный механизм сбора итоговых YAML из handlebars-шаблонов. Нас это решение устраивает, но порог погружения нового аналитика в наше решение достаточно высок, и сам процесс описания выглядит странным.
Подобное TypeSpec-решение в нашем случае могло бы помочь переложить ответственность за выработку стандартов описания на MS, мы бы себе оставили только ответственность за то, в какие папки разложить скрипты.
Язык TypeSpec для создания API-документации