APIConnect: Verwenden von $ ref, um Code-Fragmente in Ihren OpenAPI-Dateien (Swagger 2.0) wiederzuverwenden

Question

Ich verwende IBM APIConnect, um ein paar APIs zu erstellen. Ich habe versucht, die YAML-Definition meiner API zu bearbeiten, um Verweise auf Eigenschaften zu erstellen, damit ich sie externalisieren kann. Aber bis jetzt hatte ich Probleme mit der Referenzierung. Sie validieren entweder nicht gegen API API-Definition "API Connect Swagger-Erweiterungen" oder gegen "API-Definition von IBM Swagger Version 2.0-Schema".

Hier sind die beiden Referenzierung ich versucht: -

1. Referenzierung securityDefinitions: Wie in der IBM-Website beschrieben: https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapic_swagger_ref_fragment.html

mein 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 

Und es ist entsprechende Referenzdatei: -

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

auf dem übergeordneten APIC Validieren Auf tun YAML, ich die folgende Fehlermeldung erhalten: -

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. Referenzierung Eigenschaften: -

Hier ist die Eltern 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 

und die entsprechenden Referenzdatei (./schemas/properties.yaml):-

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

Bei der Validierung ist der Fehler ein anderer. Dieser YAML validiert gegen Swagger Version 2.0-Schema-API-Definition und gegen IBM Swagger Version 2.0-Schema-API-Definition, aber nicht gegen API Connect-Swagger-Erweiterungen Schema API-Definition.

Hier ist die Fehlermeldung: -

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 Ahnung, was ich hier falsch mache? P.S. In beiden Fällen validiert der Swagger die Swagger-Version 2.0-Schema-API-Definition. Es ist nur gegen die IBM spezifischen Schemas, die sie nicht tun.

Answer 1

Für jede Version 5060 oder höher funktioniert die Verwendung von $ ref nicht. Es gibt bereits einen Problembericht, der dagegen gerichtet ist. Warte auf eine zukünftige Veröffentlichung, um es zu benutzen.

Answer 2

konnte ich Ihre Frage APIConnect Version und Fixierung einen Fehler in Ihrer properties.yaml Datei lösen mit der neuesten CLI:

Version: apiconnect: v2.6.2 (API Connect: v5.0.7. 0)

Das erste, was ich hatte, war, ändern Sie die zusätzliche Typen Eigenschaft in Ihrer properties.yaml Datei zu entfernen. Ich habe den folgenden Fehler mit den Eigenschaften erhalten.YAML-Datei oben:

Additional properties not allowed (/properties/TestProperty/type)

Nach dem Entfernen des Typ Eigenschaft der Datei hat nun folgenden Inhalt:

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

habe ich dann das Validierungstool von der APIC CLI bereitgestellt sicher, dass die Konfiguration zu machen war vollständig gültig:

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]. 

Also, um Ihr Problem zu lösen, würde ich empfehlen, Ihre APIConnect Version und CLI aktualisieren und dann Entfernen Sie die Eigenschaft vom Typ aus Ihrer Datei properties.yaml. Sie sollten dann in der Lage sein, die Konfiguration erfolgreich zu validieren.