Analyseur OpenAPI
OpenAPI Linter
Contrôle un document OpenAPI et signale les réponses manquantes, les schémas inutilisés, les références qui ne pointent sur rien et les autres défauts qui cassent les générateurs de code.
Contrôle un document OpenAPI 3.0 ou 3.1 sur ce qui casse les générateurs de code, fait mentir les bibliothèques clientes, ou que la spécification exige tout simplement. Les règles sont écrites à la main et listées sur la page — des problèmes, pas des préférences de style.
Document OpenAPI
Déposez un openapi.yaml
Lu uniquement dans cet onglet.
24 constats
erreurschema-array-itemscomponents.schemas.Order.items
`type: array` sans `items`.
erreurpath-param-undeclaredGET /orders/{orderId}
`{orderId}` dans le chemin n’est pas déclaré comme paramètre.
erreurresponse-descriptionGET /orders/{orderId}
La réponse `200` n’a pas de description.
erreurschema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array` sans `items`.
erreurinfo-missinginfo
Il n’y a pas de `info.version`. C’est la version de l’API, pas celle d’OpenAPI.
erreuroperation-id-duplicatePOST /orders/{orderId}
L’operationId `getOrder` est aussi sur GET /orders/{orderId}.
erreurpath-param-requiredPOST /orders/{orderId}
Le paramètre `in: path` `id` n’a pas `required: true`.
erreurpath-param-undeclaredPOST /orders/{orderId}
`{orderId}` dans le chemin n’est pas déclaré comme paramètre.
erreurpath-param-unusedPOST /orders/{orderId}
Le paramètre `in: path` `id` n’apparaît pas dans le chemin.
avertissementpath-trailing-slash/orders/
Ce chemin se termine par `/`.
avertissementschema-unusedcomponents.schemas.Customer
Rien ne référence ce schéma.
avertissementoperation-id-missingGET /orders/
Il n’y a pas d’operationId.
avertissementresponse-errorGET /orders/
Il n’y a aucune réponse 4xx.
avertissementdescription-missingGET /orders/{orderId}
Il n’y a ni summary ni description.
avertissementresponse-errorGET /orders/{orderId}
Il n’y a aucune réponse 4xx.
avertissementdescription-missingPOST /orders/{orderId}
Il n’y a ni summary ni description.
avertissementresponse-errorPOST /orders/{orderId}
Il n’y a aucune réponse 4xx.
avertissementresponse-successPOST /orders/{orderId}
Il n’y a aucune réponse 2xx ni 3xx.
notetag-missingGET /orders/
Il n’y a pas de balise.
notetag-missingGET /orders/{orderId}
Il n’y a pas de balise.
noteparameter-descriptionPOST /orders/{orderId}
Le paramètre `id` n’a pas de description.
noteresponse-default-onlyPOST /orders/{orderId}
La seule réponse est `default`.
notetag-missingPOST /orders/{orderId}
Il n’y a pas de balise.
noteservers-missingservers
Aucun serveur n’est listé, donc l’URL de base est `/`.
OpenAPI
3.0.3
Opérations
3
Erreurs
9
Avertissements
9
Notes
6
Un jeu de règles écrit à la main. Il attrape ce qui fait trébucher un générateur de code, ce qui fait mentir une bibliothèque cliente et ce que la spécification exige vraiment — des problèmes, pas des préférences. Il ne charge pas les jeux de règles Spectral.
Pour voir ce qui a changé entre deux versions, utilisez Comparaison de versions OpenAPI.
Comment s’en servir
Collez le document
JSON ou YAML, 3.0 ou 3.1. Il est analysé dans cet onglet ; rien n'est envoyé.
Traitez d'abord les erreurs
Chaque constat porte l'identifiant de la règle et l'emplacement exact dans le document. Les erreurs sont ce qui va réellement mal tourner ; les avertissements sont ce qui tourne mal d'habitude.
Lisez la liste des règles quand un constat vous surprend
Chaque règle est écrite en toutes lettres avec sa sévérité et sa raison d'être : un constat avec lequel vous n'êtes pas d'accord est au moins un argument que vous pouvez lire.
Questions fréquentes
Peut-il charger mon jeu de règles Spectral ?
Non. C'est un jeu de règles fixe, écrit à la main, choisi pour des problèmes plutôt que pour un style maison. Si vous avez une configuration Spectral, Spectral est l'outil qui la respectera.
Il ne veut pas lire mon fichier Swagger 2.0.
C'est exact — la 2.0 est une autre forme de document, pas une 3.0 un peu plus ancienne, et la moitié des règles ne s'y appliqueraient pas. Convertissez-le d'abord ; `swagger2openapi` est la voie habituelle.
Il n'a pas suivi ma `$ref` externe.
Une `$ref` interne au document est résolue ; une qui pointe vers un autre fichier supposerait d'aller chercher un chemin que seule votre machine possède. C'est signalé par une note, pour que vous sachiez que la vérification était incomplète plutôt que nette.
Pourquoi un `operationId` manquant est-il un avertissement ?
Parce que les générateurs s'en servent pour nommer la fonction qu'ils émettent pour cette opération. Sans lui, vous obtenez un nom dérivé du chemin et de la méthode, qui change dès que le chemin change — un renommage dans votre API devient un renommage dans chaque client.
À alimenter depuis
JSON vers JSON Schema
JSON to JSON Schema
Déduit un JSON Schema à partir d’un ou plusieurs échantillons, en réunissant les formes rencontrées.
Validateur JSON Schema
JSON Schema Validator
Valide un document contre un JSON Schema et rapporte chaque échec avec le chemin exact dans l’instance.
curl vers code
curl to Code
Traduit une commande curl en fetch, axios, requests Python, Go, PHP ou PowerShell.
Comparateur OpenAPI
OpenAPI Diff
Compare deux documents OpenAPI et sépare les changements cassants des ajouts sans conséquence.
Ensuite
Ces outils acceptent ce que celui-ci produit : le résultat peut y aller directement.
curl vers code
curl to Code
Traduit une commande curl en fetch, axios, requests Python, Go, PHP ou PowerShell.
Validateur JSON Schema
JSON Schema Validator
Valide un document contre un JSON Schema et rapporte chaque échec avec le chemin exact dans l’instance.
Comparateur OpenAPI
OpenAPI Diff
Compare deux documents OpenAPI et sépare les changements cassants des ajouts sans conséquence.
Formateur et validateur YAML
YAML Formatter & Validator
Réindente le YAML de façon cohérente, le valide et signale les tabulations et les ancres qui font échouer les analyseurs.
Conversion JSON ⇄ CSV
JSON ⇄ CSV
Aplatit du JSON imbriqué en colonnes ou reconstruit des objets depuis un tableau, avec un nommage des colonnes par chemin pointé.
Comparateur JSON
JSON Diff
Compare deux documents JSON sur leur structure, sans tenir compte de l’ordre des clés, et signale les chemins ajoutés, retirés et modifiés.