Comment générer un schéma JSON à partir de la déclaration de l'API Swagger
J'ai la 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 (brouillons 3 et, plus récemment, du brouillon 4) et qu’il serait relativement facile de générer un schéma JSON pour les objets de requête et de réponse.
Cependant, bien qu'une partie de Swagger réutilise les structures de schéma JSON, il s'avère qu'elle n'utilise qu'un sous-ensemble de fonctionnalités et introduit également son propre héritage dans Models (en utilisant subTypes et discriminator.).
Question: Existe-t-il un projet ou un élément de code existant pouvant 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 quoi que ce soit).
Après une longue lutte contre l'utilisation de Swagger pour spécifier l'API REST) et la réutiliser dans des suites de tests connexes, je partagerai ma propre expérience (répondant à ma propre question).
Swagger ne prend en charge que le sous-ensemble de JSON Schema Draft 4
Spécification des états Swagger 1.2 et 2.0, il ne prend en charge que le sous-ensemble de JSON Schema Draft 4 (voir ici ). Cela signifie que:
- on ne peut pas compter sur le fait que chaque schéma JSON valide peut être entièrement pris en charge par Swagger.
- en pensant à XML, Swagger ne prend en charge que la représentation canonique de sous-ensemble de structures JSON fournie 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 pour le schéma de schéma JSON version 4 (il en va de même pour la version 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 concevoir vos données au format JSON ou XML. Avec Swagger, vous devez commencer et terminer par Swagger.
Obtenir JSON Schema 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 schéma 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 peux utiliser qu'un sous-ensemble de ce que JSON Schema fournit. Une charge JSON avait déjà été proposée et nous devions commencer à la modifier pour l'adapter à ce que les spécifications de Swagger permettaient.
En plus d'avoir une interface très agréable à regarder pour afficher et tester l'API (oui, tout le monde est d'accord, c'est visuellement très plaisant), j'ai trouvé ça bizarre qu'un framework de spécification ne nous permette pas d'utiliser ce que nous voulons, mais ajoute des restrictions inattendues à 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 d'API, j'ai trouvé RAML. Construit à partir de zéro en supportant toutes les structures de données JSON Schema Draft 3/4 ou W3C XML Schema 1.0, l'expérience a été excellente: la structure de ma charge utile étant conçue, j'ai pu créer très rapidement une spécification d'API et après validation de demandes réelles. et les réponses aux schémas définis étaient très faciles, car les schémas sont des composants essentiels de la spécification sans ajouter de restriction à ceux-ci.
RAML était à la version 0.8 de l’époque (la version 1.0 n’était pas encore disponible).
Corriger la question mène à une vraie solution
Bonne question fait la moitié de la solution. Ma question était fausse car elle ne répondait pas à mes attentes réelles. La question corrigée serait:
Quel cadre de spécification et quelle technique utiliser, à spécifier REST API utilisant la charge utile définie par le schéma JSON Schema Draft 4 ou XML Schema 1.0 arbitraire.
Ma réponse à une telle question serait:
- Concevez votre charge utile dans un schéma JSON Schema Draft 4 ou XML W3C
- Décrivez votre API REST au moyen de RAML (v0.8 pour le moment).
Il est possible que d'autres cadres de spécifications soient utilisables, mais Swagger (ni la v1.2 ni la v2.0) n'est définitivement pas le cas. En plus de fournir beaucoup de fonctionnalités (génération de code, très belle documentation de l'API et bien plus encore), il ne parvient tout simplement pas à fournir une solution à la question mise à jour énoncée ci-dessus.
Il existe un outil python permettant de faire la même chose sous le nom openapi2jsonschema . Vous pouvez simplement l’installer à l’aide de 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.
Je viens d'écrire un outil pyswagger semble correspondre à vos besoins.
Il charge la déclaration de l'API Swagger et est capable de convertir un objet python en/de primitives Swagger . Fournissez également un ensemble d'implémentations client (y compris demandes & tornado.httpclient.AsyncHTTPClient ) capable de faire une demande directement au service activé par Swagger.
Cet outil a tendance à résoudre le premier problème que j'ai rencontré lors de l'adaptation de Swagger en python et il est encore assez nouveau à présent. Bienvenue pour toute suggestion.
Vient de découvrir Swagger et me suis demandé la même chose 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 de savoir si "les modèles" font référence à un hyper-schéma JSON 4.0/JSON valide
J'ai eu du 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 le fichier JSONSchemas à partir de celui-ci. Il est assez bon d’obtenir un JSONSchema dactylographié, mais proto3 ne supporte pas les types "obligatoires".