APIConnect: Utilisation de $ ref pour réutiliser des fragments de code dans vos fichiers OpenAPI (Swagger 2.0)

Question

J'utilise APIConnect d'IBM pour créer quelques API. J'ai essayé de modifier la définition YAML de mon API pour créer des références aux propriétés afin que je puisse les externaliser. Mais jusqu'ici, je rencontrais des problèmes avec le référencement. Ils ne sont pas validés par rapport à la "définition d'API du schéma d'extensions swagger d'API Connect" ou par rapport à la "définition d'API du schéma IBM Swagger version 2.0".

Voici les deux références que j'ai essayé: -

1. securityDefinitions Référencer: Comme décrit dans le site Web d'IBM: https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapic_swagger_ref_fragment.html

mon 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 

Et il est fichier de référence correspondant: -

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

à faire un validate apic sur le parent YAML, je reçois l'erreur suivante: -

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. propriétés Référencer: -

est ici le YAML mère: -

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 

Et le fichier de référence correspondant (./schemas/properties.yaml):-

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

En validant cela, l'erreur est différente. Ce fichier YAML est validé par rapport à la définition de l'API de schéma Swagger version 2.0 et à la définition de l'API du schéma IBM Swagger version 2.0, mais pas à la définition de l'API de schéma API extensions swagger.

Voici le message d'erreur: -

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 idée de ce que je fais mal ici? P.S. Dans les deux cas, le swagger est validé par rapport à la définition de l'API du schéma Swagger Version 2.0. C'est seulement contre les schémas spécifiques d'IBM qu'ils ne le font pas.

Answer 1

Pour toute version 5060 ou ultérieure, l'utilisation de $ ref ne fonctionnera pas. Il y a un rapport de problème classé contre ceci déjà. Attendez une version future pour l'utiliser.

Answer 2

j'ai pu résoudre votre problème en utilisant la dernière CLI, la version APIConnect et la fixation d'une erreur dans votre fichier properties.yaml:

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

La première chose que j'ai dû changer était de supprimer la propriété supplémentaire de type dans votre fichier properties.yaml. Je recevais l'erreur suivante avec les propriétés.fichier YAML ci-dessus:

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

Après avoir retiré le type propriété le fichier a maintenant le contenu suivant:

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

J'ai ensuite utilisé l'outil de validation fourni par la CLI APIC pour vous assurer que la configuration était tout à fait valable:

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

Ainsi, afin de résoudre votre problème, je recommande la mise à jour de votre version APIConnect et CLI, puis supprimez la propriété type de votre fichier properties.yaml. Vous devriez alors pouvoir valider la configuration avec succès.