Apicurio-studio: Prise en charge des références aux objets de composants dans les documents de spécification

Cas d'utilisation

Le principal cas d'utilisation que cela résoudra est de donner aux utilisateurs la possibilité de centraliser leurs définitions de types de données, peut-être dans un seul fichier (ou un ensemble de fichiers). Ces types de données peuvent ensuite être exploités dans plusieurs définitions d'API en référençant leur emplacement central.

Considérations

Afin de prendre en charge les références externes, un certain nombre d'améliorations sont nécessaires. Voici une liste sans ordre particulier :

• La bibliothèque de modèles de données (actuellement oai-ts-core mais bientôt apicurio-data-models ) doit être améliorée pour prendre en charge un résolveur de référence enfichable. Actuellement, ces bibliothèques ne peuvent résoudre que les références internes. Au lieu de cela, un consommateur de la bibliothèque doit être en mesure de fournir un résolveur de référence personnalisé afin que les références externes puissent être résolues avec succès.

• Apicurio Studio doit prendre en charge une ressource de style « type de données uniquement », avec un éditeur axé sur la conception de types de données. Cela permet un flux de travail plus spécifique pour créer/gérer des types de données indépendamment des conceptions d'API.

• Lors de la définition d'un type dans l'éditeur de conception d'API, l'outillage a besoin d'un moyen de sélectionner des types à partir de ressources externes. Nous devons réfléchir à la meilleure façon d'afficher ces types externes à l'utilisateur pour la sélection. Il se peut que nous ayons besoin d'un moyen pour les conceptions d'API d'"importer" d'autres ressources/fichiers afin que l'interface utilisateur puisse affiner les choix pour l'utilisateur et les afficher judicieusement. Gardez à l'esprit que l'éditeur devra extraire et analyser toutes les ressources externes afin d'afficher leurs types de données disponibles dans une sorte de contrôle d'interface utilisateur de sélection.

• Nous devrons peut-être décider si les ressources de type de données en cours peuvent être utilisées comme source de références externes dans une conception d'API. En d'autres termes, devrait-il être possible de référencer des types de données « instantanés » dans une conception d'API ? Ou devrions-nous exiger qu'une ressource de type de données soit « finale » avant qu'elle puisse être utilisée comme source de références externes. Si c'est le cas, nous ne pouvons pas « finaliser » une conception d'API tant que ses dépendances ne sont pas également finalisées. Remarque : tout ce concept nous oblige à implémenter des ressources de finalisation dans Apicurio !

• Nous devrons décider quel sera le format $ref lors du référencement des ressources Apicurio. Actuellement, toute conception d'API (ou ressource de types de données théoriques) a un identifiant unique, mais c'est un identifiant opaque qui est généré lors de la création. Cet ID est actuellement le seul moyen unique d'identifier une ressource à des fins de résolution. Une fois qu'une ressource est finalisée (si nous soutenons un tel concept), nous pourrions peut-être accorder à la ressource un identifiant plus convivial et l'utiliser ensuite dans l'URI $ref. Quoi que nous fassions, il convient de noter que lors de la publication d'une ressource dans un registre d'API (une autre fonctionnalité future), toutes les références $ dans la conception d'API devront être résolues par le registre d'API d'une manière raisonnable.

Voici quelques informations sur les valeurs autorisées pour un $ref :

Même si la valeur d'un $ref est un URI, ce n'est pas un localisateur de réseau, seulement un identifiant. Cela signifie que le schéma n'a pas besoin d'être accessible à cet URI, mais il peut l'être. Il appartient essentiellement à l'implémentation du validateur de gérer les URI de schéma externes, mais il ne faut pas supposer que le validateur récupérera les ressources réseau indiquées dans les valeurs $ref.

Vous trouverez plus d'informations sur les références dans la spécification OpenAPI et la RFC de référence JSON .

Serait-il possible de prioriser la mise en œuvre des références aux DataTypes d'une autre spécification au sein d'Apicurio (plutôt que des références externes initialement) ?

La raison pour laquelle je dis cela est que certaines fonctionnalités de référence croisée sont nécessaires pour toute utilisation non triviale de Swagger. Par exemple, nous mettons en œuvre divers services qui partagent des types de données (par exemple, des adresses, des personnes, etc.) et aimerions utiliser Apicurio pour les spécifications de tous ceux-ci. Cependant, pour le moment, nous ne pouvons pas en raison de l'impossibilité d'utiliser des références croisées.

Serait-il possible de prioriser la mise en œuvre des références aux DataTypes d'une autre spécification au sein d'Apicurio (plutôt que des références externes initialement) ?

La raison pour laquelle je dis cela est que certaines fonctionnalités de référence croisée sont nécessaires pour toute utilisation non triviale de Swagger. Par exemple, nous mettons en œuvre divers services qui partagent des types de données (par exemple, des adresses, des personnes, etc.) et aimerions utiliser Apicurio pour les spécifications de tous ceux-ci. Cependant, pour le moment, nous ne pouvons pas en raison de l'impossibilité d'utiliser des références croisées.

D'accord, cela nous amènerait sur le territoire des applications tueuses.

@jsenko Il semble qu'une fois l'

J'adorerais voir cela, utiliser apicurio au travail et des références serait incroyablement utile à différentes équipes.

Je me rends compte que cela a pris un peu de temps, mais les références externes seront officiellement prises en charge à partir de la version bêta 2.46, qui est la prochaine version (sera, espérons-le, faite demain). Il existe une nouvelle interface utilisateur pour importer les types de données et les réponses d'autres documents Apcurio Studio dans le document actuel. De plus, la validation a été mise à jour pour prendre en charge la résolution des http/s externes ainsi que les références internes d'Apicurio. Cela devrait être un bon premier pas vers une prise en charge mature des références entre les documents.