APIConnect：使用$ref重用OpenAPI（Swagger 2.0）文件中的代码片段

Question

我使用IBM的APIConnect来创建一些API。我一直试图编辑我的API的YAML定义来创建对属性的引用，这样我就可以将它们具体化。但到目前为止，我遇到了引用的问题。它们或者不根据“API Connect Swagger extensions schema API定义”或者“IBM Swagger Version 2.0 schema API定义”进行验证。

以下是我尝试的两个参考：-

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

在对父 YAML 进行 apic 验证时，我收到以下错误：-

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.

这是父 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验证Swagger 2.0版模式API定义和IBM Swagger版模式API定义，但不验证API Connect swagger扩展模式API定义。

下面是错误消息:-

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.

你知道我做错了什么吗？在这两种情况下，swagger根据“Swagger版本2.0模式API定义”进行验证。他们不这样做只是违背了IBM特定的模式。

Answer 1

对于任何版本 5060 或更高版本，都无法使用 $ref。已经有针对此提交的问题报告。等待将来的版本使用它。

Answer 2

我能够使用最新的CLI、APIConnect版本并修复properties.yaml文件中的一个错误来解决您的问题:

v2.6.2（API Connect： v5.0.7.0）

我要做的第一件事是删除properties.yaml文件中的附加类型属性。我在上面的properties.yaml文件中收到以下错误:

不允许其他属性（/properties/TestProperty/type）

删除类型属性后，文件现在包含以下内容:

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

然后，我使用apic CLI提供的验证工具来确保配置完全有效：

macbook-pro-92:Test Algebra$ apic validate Test.yaml
Successfully validated Test.yaml against Swagger Version 2.0 schema API definition [pokemonapp:1.0.0].
Successfully validated Test.yaml against API Connect swagger extensions schema API definition [pokemonapp:1.0.0].
Successfully validated Test.yaml against IBM Swagger Version 2.0 schema API definition [pokemonapp:1.0.0].

因此，为了解决您的问题，我建议更新您的APIConnect版本和CLI，然后从properties.yaml文件中删除type属性。然后，您应该能够成功验证配置。