Comment générer un schéma JSON à partir de la déclaration de l’API Swagger

J’ai une déclaration API Swagger pour les services utilisant Swagger v 1.2

Mon sentiment initial à propos de Swagger était qu’il était très proche du schéma JSON (Draft 3 et Draft 4) et qu’il serait relativement facile de générer un schéma JSON pour les objects de requête et de réponse.

Cependant, même si une partie du Swagger réutilise les structures du schéma JSON, il s’est avéré qu’il n’utilisait qu’un sous-ensemble de fonctionnalités et qu’il introduisait également son propre inheritance dans les modèles (utilisant des sous- subTypes et un discriminator ).

Question: Existe-t-il un projet ou un morceau de code existant qui peut générer un schéma JSON utilisable à partir de la déclaration de l’API Swagger ?

Optimalement JSON Schema Draft 4 et en utilisant Python (mais je serai heureux de trouver quelque chose).

Après un long combat avec l’utilisation de Swagger pour spécifier l’API REST et sa réutilisation dans des suites de tests associées, je partagerai ma propre expérience (en répondant à ma propre question).

Swagger ne prend en charge que le sous-ensemble de JSON Schema Draft 4

La spécification des états Swagger 1.2 et 2.0 ne prend en charge que le sous-ensemble de JSON Schema Draft 4 (s. Ici ). Cela signifie que:

  • On ne peut pas compter que chaque schéma JSON valide peut être complètement pris en charge par Swagger.
  • En pensant à XML, Swagger ne prend en charge que la représentation canonique du sous-ensemble des structures JSON fournies par JSON Schema Draft 4.

En d’autres termes:

  • Swagger (1.2 et 2.0) ne prend pas en charge l’utilisation de nombreuses structures JSON, qui sont valides en termes de JSON Schema Draft 4 (il en va de même pour Draft 3).
  • Swagger ne prend pas en charge les structures de données XML générales, seules les structures très restreintes sont autorisées.

En pratique, vous ne pouvez pas commencer avec la conception de vos données en JSON ou XML. Avec Swagger, vous devez commencer et terminer avec Swagger.

Obtenir un schéma JSON est théoriquement possible, mais pas facile

J’ai passé du temps à coder une bibliothèque, qui prendrait les spécifications de l’API Swagger et créerait le JSON Schema Draft 4. J’ai abandonné pour deux raisons:

  • ce n’était pas facile du tout
  • J’ai été déçu de constater que je ne pouvais utiliser que le sous-ensemble de ce que fournit JSON Schema. Nous avons déjà proposé des payloads JSON et nous avons dû commencer à les modifier pour que le framework de spécification Swagger le permette.

En plus d’avoir une interface utilisateur très agréable pour afficher et tester l’API (oui, tout le monde est d’accord, c’est très agréable visuellement), j’ai trouvé bizarre qu’un framework de spécification ne nous permette pas à notre conception.

Si vous souhaitez une prise en charge complète du schéma JSON ou XML, utilisez RAML

En recherchant d’autres frameworks de spécification API, j’ai trouvé RAML. Comme il a été conçu en prenant en charge toutes les structures de données JSON Schema Draft 3/4 ou W3C XML Schema 1.0, l’expérience était excellente – la structure de ma charge utile étant conçue, j’ai pu créer très rapidement des spécifications API et valider des requêtes réelles et les réponses à des schémas définis étaient très faciles, car les schémas sont des composants essentiels de la spécification sans y append de ressortingctions.

RAML était à la version 0.8 cette fois (la version 1.0 n’était pas encore sortie).

Corriger la question conduit à une vraie solution

Une bonne question fait la moitié de la solution. Ma question était fausse car elle manquait à mes attentes réelles. La question corrigée serait:

Quel cadre de spécification et technique utiliser, pour spécifier l’API REST à l’aide de données utiles définies par un schéma JSON Schema 4 ou W3C XML arbitraire 1.0.

Ma réponse à une telle question serait:

  1. Concevez votre charge utile en JSON Schema Draft 4 ou W3C XML Schema
  2. Décrivez votre API REST au moyen de RAML (v0.8 pour le moment).

Il pourrait y avoir d’autres frameworks de spécification utilisables, mais Swagger (ni v1.2 ni v2.0) n’est certainement pas le cas. En plus de fournir de nombreuses fonctionnalités (génération de code, documentation très intéressante de l’API et bien plus encore), il ne suffit pas de fournir une solution à la question posée ci-dessus.

Je viens d’écrire un outil que pyswagger semble correspondre à votre besoin.

Il charge la déclaration de l’API Swagger et peut convertir l’ object python en / depuis les primitives Swagger . Fournissez également un ensemble d’implémentations client (y compris les requêtes & tornado.httpclient.AsyncHTTPClient ) capables de faire directement une demande au service compatible Swagger.

Cet outil a tendance à résoudre le premier problème rencontré lors de l’adaptation de Swagger en Python, et il est encore assez récent. Bienvenue pour toute suggestion.

Je viens juste de découvrir Swagger et je me suis posé la même question car ce serait une exigence.

Trouvé cette réponse

Essayez-le directement à partir d’ici:

http://petstore.swagger.wordnik.com/

et mettez ceci comme votre URL:

http://petstore.swagger.wordnik.com/api/api-docs/pet

Je vois tous les modèles. N’est-ce pas Ou est-ce que je manque quelque chose?

ici dans leur groupe d’utilisateurs: https://groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

la question est si “les modèles” fait référence à un schéma JSON 4.0 / hyper-schéma JSON valide

Il existe un outil python pour faire la même chose sous le nom openapi2jsonschema . Vous pouvez simplement l’installer en utilisant pip .

Le readme pour openapi2 montre la manière la plus simple de l’utiliser:

 openapi2jsonschema https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json 

J’espère que cela t’aides.

J’ai eu un certain succès en le faisant comme ceci:

swagger.yaml -> proto -> jsonschema

J’ai utilisé openapi2proto pour générer des fichiers proto à partir de Swagger yaml, puis protoc-gen-jsonschema pour générer les JSONSchemas à partir de cela. C’est assez bon pour obtenir un JSONSchema typé, mais proto3 ne supporte pas les types “obligatoires”, donc vous manquez cette possibilité.