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

Question

我正在使用IBM的APIConnect創建一些API。我一直試圖編輯我的API的YAML定義來創建對屬性的引用，以便我可以將它們外部化。但到目前爲止，我一直在遇到與參考有關的問題。它們要麼不針對「API Connect swagger擴展模式API定義」進行驗證，要麼針對「IBM Swagger 2.0版模式API定義」進行驗證。

這裏有兩個引用我想： -

1. 引用securityDefinitions： 在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 2.0版架構API定義進行驗證，但不針對API Connect易怒擴展架構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. 

阿努知道我做錯了嗎？ P.S.在這兩種情況下，swagger都會針對'Swagger 2.0版模式API定義'進行驗證。它只是針對IBM不具備的具體模式。

Answer 1

對於任何版本5060或更高版本，使用$ ref將不起作用。這裏已經有一個問題報告。等待將來的版本使用它。

Answer 2

我能解決使用最新的CLI，APIConnect版本，並在您的properties.yaml文件修復錯誤您的問題：

版本： apiconnect：V2.6.2（API連接：v5.0.7。 0）

我必須改變的第一件事是在你的properties.yaml文件中刪除額外的類型屬性。我收到以下錯誤的屬性。YAML文件之上：

Additional properties not allowed (/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文件中刪除類型屬性。然後，您應該能夠成功驗證配置。