Générateur de schémas de réponse JSON vers OpenAPI
Déduisez un schéma de réponse à partir d’échantillons JSON et générez un chemin YAML OpenAPI 3.0.3.
Fonctionnement
Collez un échantillon JSON de réponse, saisissez un chemin littéral et choisissez GET, POST, PUT ou DELETE. Le générateur déduit le schéma du corps de réponse et le place dans un document YAML OpenAPI 3.0.3.
Utilisez des échantillons représentatifs pour montrer les variations possibles de la réponse. Lorsque plusieurs objets apparaissent au même emplacement d’un tableau, le générateur combine leurs propriétés et ne marque une propriété obligatoire que si chaque objet observé la contient.
Vérifiez les types déduits et les champs obligatoires avant d’utiliser le YAML. Ajoutez vous même les corps de requête, paramètres, règles d’authentification, réponses d’erreur et déclarations de paramètres de chemin. Validez ensuite le document complet avec un validateur OpenAPI.
Utilisez cet outil lorsque vous avez des exemples JSON mais pas de schéma de réponse. Il documente uniquement le chemin et la méthode sélectionnés à partir de l’échantillon fourni.
Étape par étape
- Collez un échantillon JSON de réponse
- Indiquez un chemin littéral et choisissez la méthode
- Vérifiez et copiez le schéma de réponse
Exemple détaillé
Pour GET /api/users, collez {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}. L’échantillon contient des objets imbriqués, des valeurs mixtes dans un tableau et deux objets de métriques.
La sortie rend user, tags et metrics obligatoires. Les deux objets de métriques contiennent count, qui est donc également obligatoire. score et active n’apparaissent chacun que dans un objet, ils sont donc facultatifs. tags accepte une chaîne ou un entier, et chaque type observé est nullable puisque l’échantillon contient aussi null.
Quand utiliser cet outil
Utilisez le générateur pour convertir des corps JSON de réponse d’exemple en un premier schéma OpenAPI lors de la documentation d’un chemin.
Il aide à organiser les formes de réponse observées. Le document généré nécessite encore les détails de requête, de sécurité, d’erreur et de paramètres de votre API.
Erreurs fréquentes
Avec un seul objet, toutes les propriétés présentes semblent obligatoires. Pour identifier les propriétés qui varient entre les réponses, fournissez plusieurs objets représentatifs au même emplacement d’un tableau.
Ne considérez pas la sortie déduite comme une définition API complète. Vérifiez le traitement de null, les champs facultatifs, les variantes de tableaux et les chemins littéraux. Ajoutez les détails de requête et d’erreur qui ne sont pas couverts par cet outil.
Règles de déduction
Pour chaque emplacement d’objet, clés obligatoires = clés présentes dans tous les objets observés.
Pour chaque valeur, schéma déduit = union des types non nuls observés.
Quand null est observé avec un type connu, ce schéma typé est marqué nullable.
Cette déduction repose sur des échantillons et ne vérifie pas un contrat à l’exécution. Un exemple ne permet pas de savoir quels champs les réponses de production peuvent omettre.
Limites et hypothèses
Le résultat décrit les valeurs observées dans l’échantillon. Il ne peut pas identifier les champs absents de tous les exemples, prouver qu’un champ est facultatif en production ou déduire le type d’un élément d’un tableau vide. Une valeur uniquement observée comme null n’a pas de type déductible. Les valeurs mixtes sont représentées comme des alternatives à comparer avec le contrat de votre API.
Termes clés
- Document OpenAPI
- Un document OpenAPI décrit les chemins, opérations, entrées, réponses et autres détails d’une API dans un format lisible par machine.
- Schéma
- Un schéma décrit la structure attendue et les types de valeurs, par exemple un objet avec des propriétés nommées.
- Propriété obligatoire
- Dans cette sortie, obligatoire signifie que la propriété figurait dans chaque objet observé à cet emplacement. Cela ne prouve pas le comportement en production.
Comparer les outils associés
Utilisez le convertisseur YAML vers JSON pour obtenir du JSON à partir d’une entrée YAML prise en charge. Utilisez SQL vers TypeScript pour obtenir des types TypeScript depuis une définition de table. Cet outil déduit un schéma de réponse à partir d’échantillons JSON.
Le générateur de données simulées pour API crée des lignes à partir d’un objet JSON d’exemple. Cet outil déduit un schéma de réponse depuis un échantillon JSON et ne génère pas de données simulées.
FAQ
Comment le générateur crée un schéma de réponse à partir de l’échantillon ?
Le générateur examine chaque valeur de l’échantillon JSON. Il crée des propriétés d’objet, inspecte tous les éléments des tableaux et combine les types observés avec anyOf si nécessaire. Par exemple, le tableau tags de l’exemple contient des chaînes, null et un entier, son schéma d’élément accepte donc une chaîne nullable ou un entier nullable.
Comment représenter null et les autres types ?
Les objets deviennent des schémas avec des propriétés. Une propriété est obligatoire lorsqu’elle est présente dans chaque objet observé à cet emplacement. Les valeurs de types différents utilisent anyOf. Si null et un autre type sont observés, le schéma typé reçoit nullable: true. Une valeur uniquement observée comme null n’a pas de type déductible, son schéma reste donc sans contrainte.
Que contient le document généré ?
Le document contient un chemin, la méthode choisie GET, POST, PUT ou DELETE et une réponse JSON réussie de statut 200. Le schéma est enregistré dans components et référencé par la réponse. Le générateur ne crée ni corps de requête, ni paramètres, ni règles de sécurité, ni réponses d’erreur, ni noms de champs HTTP.
Pourquoi le générateur rejette les routes avec un identifiant dans le chemin ?
Le chemin doit être littéral et commencer par une barre oblique, par exemple /api/users. Les chemins avec des accolades sont refusés, car un modèle comme /api/users/{id} nécessite aussi un paramètre de chemin déclaré que ce générateur n’ajoute pas.
Cette sortie forme un contrat API complet ?
Non. La sortie décrit le corps d’une réponse d’exemple. Elle ne déduit pas les schémas de requête et ne valide pas le YAML généré selon la spécification OpenAPI. Ajoutez les autres opérations et détails de réponse, puis vérifiez le document complet avec un validateur OpenAPI.
Outils associés
Le convertisseur YAML vers JSON convertit les entrées YAML prises en charge en JSON. SQL vers TypeScript produit des déclarations de types à partir de structures SQL. Le générateur de données simulées pour API crée des lignes depuis un objet JSON d’exemple. Cet outil déduit un schéma de réponse à partir d’échantillons JSON.