Я работаю над проектом, в котором мы переписываем интерфейс существующего приложения, перенося все на swagger / openAPI.
Прямо сейчас у каждой функции есть свой собственный файл yml, который является отдельной спецификацией. ,Но есть некоторые недостатки:
- дублированный контент в файлах yml (например, модели, которые могут использоваться в разных файлах)
- дублированный код программы (который генерируется из этих файлов yml).
- необходимо обрабатывать каждый файл yml индивидуально при использовании инструментов.
В идеале мы хотели бы иметь отдельную папку для каждой службы с моделями и службами. описание для этой конкретной услуги близко друг к другу, но отделено от других услуг. Конечно, существуют также общие модели, которые мы затем хотим разместить в другой папке (например, «/ shared-models»). И наконец, мы хотим, чтобы все эти файлы были включены в 1 основной корневой файл yml .
Итак, мы рассматривали разбиение / импорт файлов с атрибутом $ref. Но сложно придумать полноразмерную структуру файлов и папок , потому что спецификация позволяет использовать $ref в некоторых местах, но не во всех местах. Вы не можете просто разбивать и структурировать файлы так, как вам нравится. Поэтому нам, вероятно, понадобится какой-то компромисс.
Мне было особенно интересно, как другие компании делают эту настройку. (например, пример установки, которая использует структуру размашистых файлов на уровне предприятия, была бы превосходной.) Мы хотели бы сделать вещи простыми и по возможности в соответствии со стандартами или популярными соглашениями .
(для ясности: у меня вопрос не такой: «как использовать $ ref»)