Cette page est le guide canonique pour analyser des documents OpenAPI et Swagger dans le navigateur avec DevUtilities. Collez une spécification ci-dessus pendant la lecture, ou sautez vers un sujet ci-dessous. La validation reste locale — les documents ne sont jamais téléversés. Lorsque le lint est vert, transférez vers Kiota SDK Engine pour le score de préparation et l’aperçu de la commande generate.

OpenAPI Validator est un linter côté client pour OpenAPI 3 et Swagger 2 en JSON/YAML. Il signale VALID, VALID WITH WARNINGS ou INVALID avec des diagnostics liés aux chemins afin de corriger les bloqueurs avant la génération SDK ou l’import gateway.

Ce que vous obtenez

• Analyse les documents OpenAPI 3.x et Swagger 2 (JSON ou YAML)
• Bannière d’état : VALID / VALID WITH WARNINGS / INVALID
• Vérifie les clés de version, la couverture des paths, servers et les problèmes structurels courants
• Lint uniquement local — sûr pour les specs d’API internes
• Chemin direct vers Kiota SDK Engine pour la préparation codegen

Utilisez cet outil lorsque

• Vous avez besoin d’un contrôle rapide avant Microsoft Kiota ou d’autres générateurs
• CI ou une checklist de PR exige un lint lisible de la spec validée
• Vous avez hérité d’un fichier Swagger 2 et voulez des avertissements de migration avant le travail OpenAPI 3
• Des operationId en double ou des $ref cassés continuent de casser le codegen

Préférez un outil associé lorsque

• Vous avez besoin du score Kiota complet, de la matrice de langages et du constructeur CLI → Kiota SDK Engine
• Vous voulez seulement embellir des payloads JSON → JSON Formatter
• Vous avez besoin de tableaux de réponses fictives → JSON Generator

Les générateurs de code (surtout Kiota) échouent bruyamment sur des problèmes structurels qu’un coup d’œil YAML manque. Analysez ici d’abord, puis ouvrez Kiota SDK Engine pour la préparation spécifique au générateur.

Bloqueurs à lever avant le codegen

• operationId en double ou manquant (collisions de noms de méthodes)
• responses manquantes ou vides sur les codes de succès
• $ref invalide ou orphelin vers components
• Clé openapi/swagger manquante ou objet paths vide
• Références de schema circulaires (souvent visibles ensuite dans Kiota)

Avertissements que vous pouvez différer

• servers[] manquant — les clients peuvent avoir besoin d’overrides --base-url
• Notes de migration Swagger 2 — préférez OpenAPI 3 pour les nouvelles API
• Descriptions rares — qualité documentaire, pas des bloqueurs d’analyse

Parcours initial avant de générer un SDK.

1. Collez OpenAPI 3 ou Swagger 2 en JSON ou YAML dans le panneau d’entrée.
2. Lisez l’état : VALID, VALID WITH WARNINGS ou INVALID.
3. Corrigez chaque erreur de la liste de diagnostics — commencez par operationId, responses et échecs $ref.
4. Relancez jusqu’à VALID ou jusqu’à ce qu’il ne reste que des avertissements acceptables.
5. Transférez la spec nettoyée vers Kiota SDK Engine pour le score, l’aperçu de langage et la commande kiota generate.
6. Validez le document corrigé et ajoutez éventuellement ce lint comme item de checklist PR.

Les pull requests fusionnent des modifications OpenAPI qui cassent ensuite la régénération nocturne du SDK. Les relecteurs ne peuvent pas repérer des operationId en double à l’œil.

Comment cet outil le résout

1. Collez le document OpenAPI du PR dans le validateur pendant la revue.
2. Exigez VALID (ou uniquement des avertissements documentés) avant d’approuver.
3. Signalez les operationId en double et les $ref cassés dans le fil de revue avec le texte du diagnostic.
4. Après le merge, exécutez Kiota en CI sur le même document.

Une porte de lint à vitesse humaine qui capture la même classe d’échecs que les générateurs — sans téléverser la spec.

Une équipe s’apprête à exécuter kiota generate et veut la confiance que le document ne échouera pas sur les noms ou les $ref.

Comment cet outil le résout

1. Analysez le document ici jusqu’à éliminer INVALID.
2. Transférez vers Kiota SDK Engine et examinez le score OpenAPI Readiness.
3. Corrigez les problèmes restants spécifiques à Kiota (refs circulaires, style nullable) dans les diagnostics Kiota.
4. Copiez la commande CLI générée une fois la préparation acceptable.

Un flux local en deux étapes : lint structurel → préparation Kiota → generate sur votre machine.

Un ancien JSON Swagger 2 alimente encore une passerelle. Les parties prenantes veulent OpenAPI 3 avant d’adopter Kiota.

Comment cet outil le résout

1. Collez le document Swagger 2 et notez les avertissements de migration.
2. Corrigez les problèmes structurels INVALID qui bloqueraient tout convertisseur.
3. Planifiez une migration OpenAPI 3 pour les nouvelles fonctionnalités ; gardez Swagger 2 seulement tant qu’il est bridé.
4. Réanalysez le résultat OpenAPI 3 avant Kiota.

Signal clair que Swagger 2 est analysé avec des avertissements — préférez OpenAPI 3 pour un nouveau travail SDK.

Les générateurs nomment les méthodes client d’après operationId. Les doublons provoquent des collisions.

Pourquoi cela arrive

Deux opérations ou plus partagent le même operationId, ou operationId manque là où le générateur l’exige.

Diagnostic

Recherchez dans le document les valeurs operationId répétées. Kiota et ce linter signalent les collisions — corrigez ici avant d’ouvrir le moteur SDK.

Correctifs

1. Attribuez un operationId unique à chaque opération (verbe + ressource est un schéma courant).
2. Supprimez les paths dupliqués inutilisés copiés pendant l’édition.
3. Si vous réduisez pour un SDK partiel, retirez les paths en conflit plutôt que de renommer à la légère des IDs de production.

Après renommage, relancez l’analyse puis revérifiez la préparation Kiota — les noms de méthodes dans les aperçus changeront.

Les opérations sans responses utilisables cassent la génération de clients typés.

Pourquoi cela arrive

Une opération de path omet responses, ou les responses de succès ont un content {} vide sans schema.

Diagnostic

Inspectez la carte responses de chaque opération pour les entrées 200/201 (ou default) et assurez-vous que les schemas de content se résolvent.

Correctifs

1. Ajoutez au moins une response de succès avec un media type application/json (ou pertinent).
2. Pointez le schema de content vers components.schemas via $ref au lieu de laisser content vide.
3. Documentez les responses d’erreur (4xx/5xx) lorsque les clients doivent les gérer — des avertissements peuvent rester si elles sont omises.

Les pointeurs $ref invalides empêchent la résolution des schemas pendant le lint et le codegen.

Pourquoi cela arrive

Un $ref cible un component manquant, utilise un JSON Pointer incorrect ou forme un cycle que le résolveur ne peut pas développer.

Diagnostic

Suivez chaque chemin $ref en échec dans components.schemas / parameters / responses. Confirmez que la clé cible existe et que l’orthographe correspond.

Correctifs

1. Réparez ou recréez la cible du component manquant.
2. Normalisez les chaînes $ref en pointeurs #/components/...
3. Brisez les références circulaires en extrayant des DTO peu profonds (le guide des refs circulaires de Kiota s’applique ensuite).

Interprétez la bannière avant de modifier le document.

OpenAPI Validator et Kiota SDK Engine sont complémentaires. Analysez la santé structurelle ici ; utilisez Kiota pour la préparation du générateur, la matrice de langages, la sélection d’endpoints et l’export de commande CLI.

• Transférez ou collez la spec nettoyée dans Kiota SDK Engine après VALID.
• Utilisez les diagnostics Kiota pour les operationId en double, les $ref circulaires et les problèmes de style nullable que les générateurs soulignent.
• Copiez kiota generate depuis l’étape Kiota Generate — l’émission de fichiers s’exécute toujours via la CLI Kiota locale.
• Gardez les deux outils côté client pour que les contrats d’API internes ne quittent jamais le navigateur.

• Analysez à chaque PR OpenAPI avant d’approuver.
• Préférez OpenAPI 3 pour les nouvelles API ; traitez Swagger 2 comme legacy avec avertissements de migration.
• Rendez operationId unique et stable — les renommages agitent les clients générés.
• Donnez toujours aux responses de succès un schema résolvable.
• Éliminez INVALID avant d’ouvrir Kiota ; utilisez ensuite Kiota pour la préparation spécifique au générateur.
• Ne téléversez pas de specs internes vers un lint SaaS tiers lorsque ce chemin local suffit.