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

Question

我正在使用 IBM 的 APIConnect 创建一些 API。我一直在尝试编辑我的 API 的 YAML 定义以创建对属性的引用，以便我可以将它们外部化。但到目前为止，我一直遇到引用问题。它们要么不针对“API Connect swagger 扩展架构 API 定义”进行验证，要么不针对“IBM Swagger 版本 2.0 架构 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.

1. 引用属性：-

这是父 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 版本 2.0 架构 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.

Anu 知道我在这里做错了什么吗？ 附言在这两种情况下，swagger 都会根据“Swagger 版本 2.0 架构 API 定义”进行验证。只是针对 IBM 特定的模式，他们不这样做。

Answer 1

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

版本： apiconnect：v2.6.2（API Connect：v5.0.7.0）

我必须更改的第一件事是删除 properties.yaml 文件中的附加 type 属性。我在上面的 properties.yaml 文件中收到以下错误：

不允许附加属性 (/properties/TestProperty/type)

删除 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 属性。然后，您应该能够成功验证配置。

Answer 2

对于任何版本 5060 或更高版本，使用 $ref 将不起作用。已经有针对此的问题报告。等待未来的版本使用它。