OpenAPI из нескольких файлов: $ref между файлами проекта

Спецификация на несколько сотен методов в одном файле неудобна: долго искать, тяжело ревьюить, конфликты при совместной правке. Её разбивают на файлы — общие схемы отдельно, группы методов отдельно — и связывают ссылками $ref.

Как устроить проект

1. Создайте проект и в виде По папкам — папки, например api и common.
2. Положите главную спецификацию в api/orders.yaml, общие схемы — в common/types.yaml.
3. Ссылайтесь на общие схемы относительным путём:

   customer:
     $ref: '../common/types.yaml#/components/schemas/Customer'

4. Откройте api/orders.yaml: документация справа покажет и схемы из общего файла.

Как разрешаются ссылки

• Путь — от папки текущего файла (../common/…) или от корня проекта (/common/…).
• После # — указатель внутри файла (JSON Pointer): #/components/schemas/Customer.
• Регистр букв в именах файлов не важен.
• Внешние адреса (https://…) не загружаются.

Навигация

• Ctrl+клик по $ref на другой файл открывает его в новой вкладке сразу на нужной схеме.
• Если путь неверный, редактор сообщит, что файл не найден.
• Путь, по которому на артефакт ссылаются, показывается в дереве проекта.

То же для AsyncAPI и JSON Schema

Ссылки работают одинаково в редакторах AsyncAPI (схемы сообщений) и JSON Schema (общие определения). Преобразования тоже их учитывают: например, при переводе OpenAPI в JSON Schema схемы из связанных файлов встраиваются в результат.

Совет по структуре

Выносите в общие файлы то, что действительно переиспользуется: типы денег и дат, ошибки, пагинацию. Слишком мелкое дробление усложняет навигацию сильнее, чем помогает.

Пример

common/types.yaml:

components:
  schemas:
    Money:
      type: object
      required: [amount, currency]
      properties:
        amount: {type: number}
        currency: {type: string, enum: [RUB, USD]}
    Error:
      type: object
      properties:
        code: {type: string}
        message: {type: string}

api/orders.yaml:

components:
  schemas:
    Order:
      type: object
      properties:
        total:
          $ref: '../common/types.yaml#/components/schemas/Money'
  responses:
    NotFound:
      description: Не найдено
      content:
        application/json:
          schema:
            $ref: '../common/types.yaml#/components/schemas/Error'

Вопросы и ответы

Можно ли собрать спецификацию в один файл? Для схем — да: преобразование в JSON Schema встраивает все связанные схемы в один документ. Полную сборку спецификации (bundle) делают инструменты вроде Redocly CLI — скачайте файлы проекта архивом и соберите локально.

Как ссылаться на файл в соседнем проекте? Никак: ссылки разрешаются внутри одного проекта. Общие схемы нескольких систем держите в одном проекте или копируйте.