APIConnect: использование $ ref для повторного использования фрагментов кода в файлах OpenAPI (Swagger 2.0)

Я использую IBM APIConnect для создания нескольких API. Я пытался отредактировать определение YAML моего API, чтобы создать ссылки на свойства, чтобы я мог их экстернализовать. Но пока у меня проблемы со ссылками. Они либо не проверяются на соответствие «определению API схемы расширений API Connect Swagger» или «определению API схемы IBM Swagger версии 2.0».

Вот две ссылки, которые я пробовал: -

1. Ссылки на определения безопасности: Как описано на веб-сайте IBM: https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapic_swagger_ref_fragment.html

мой YAML: -

swagger: '2.0'
info:
  version: 1.0.0
  title: PokemonApp
  x-ibm-name: pokemonapp
host: $(catalog.host)
basePath: /api
paths:
  /pokemon:
    get:
      responses:
        '200':
          description: 200 OK
securityDefinitions:
    $ref: ./schemas/ClientID.yaml
security:
  - clientID: []
x-ibm-configuration:
  assembly:
    execute:
      - invoke:
          target-url: $(TestProperty)
  properties:
    TestProperty:
        value: 'https://pokemons.mybluemix.net/api/pokemons'
        description: ''
        encoded: false
  gateway: micro-gateway

И соответствующий справочный файл: -

clientID:
    description: ''
    in: query
    name: client_id
    type: apiKey

При выполнении проверки apic на родительском YAML я получаю следующую ошибку: -

C:\Users\MyName\TestNotes\definitions>apic validate pokemonapp_1.0.0.yaml
Successfully validated pokemonapp_1.0.0.yaml against Swagger Version 2.0 schema API definition [pokemonapp:1.0.0].
Successfully validated pokemonapp_1.0.0.yaml against API Connect swagger extensions schema API definition [pokemonapp:1.0.0].
Error validating pokemonapp_1.0.0.yaml with IBM Swagger Version 2.0 schema API definition [pokemonapp:1.0.0].
  Data does not match any schemas from "oneOf" (/securityDefinitions/$ref)
Error: Validation did not complete successfully.

2. Ссылочные свойства: -

Вот родительский YAML: -

swagger: '2.0'
info:
  version: 1.0.0
  title: PokemonApp
  x-ibm-name: pokemonapp
host: $(catalog.host)
basePath: /api
paths:
  /pokemon:
    get:
      responses:
        '200':
          description: 200 OK
securityDefinitions:
    clientID:
        description: ''
        in: query
        name: client_id
        type: apiKey
security:
  - clientID: []
x-ibm-configuration:
  assembly:
    execute:
      - invoke:
          target-url: $(TestProperty)
  properties:
    $ref: ./schemas/properties.yaml
  gateway: micro-gateway

И соответствующий справочный файл (./schemas/properties.yaml):-

TestProperty:
    type: object
    value: 'https://pokemons.mybluemix.net/api/pokemons'
    description: ''
    encoded: false

После проверки это другая ошибка. Этот YAML проверяет соответствие определению API схемы Swagger Version 2.0 и определение API схемы IBM Swagger Version 2.0, но не соответствует определению API схемы расширений Swagger API Connect.

Вот сообщение об ошибке: -

C:\Users\MyName\TestNotes\definitions>apic validate pokemonapp_1.0.0.yaml
Successfully validated pokemonapp_1.0.0.yaml against Swagger Version 2.0 schema API definition [pokemonapp:1.0.0].
Error validating pokemonapp_1.0.0.yaml with API Connect swagger extensions schema API definition [pokemonapp:1.0.0].
  Invalid type: string (expected object) (/properties/$ref)
Successfully validated pokemonapp_1.0.0.yaml against IBM Swagger Version 2.0 schema API definition [pokemonapp:1.0.0].
Error: Validation did not complete successfully.

Ану идея, что я здесь делаю не так? P.S. в обоих случаях swagger проверяет соответствие «определению API схемы Swagger версии 2.0». Они этого не делают только против специфических схем IBM.