Softonic

Contrôle des champs obligatoires OpenAPI

Étape 1 / 2
Suivant

Avant de transmettre une description d’API à un collègue, à un client ou à un générateur de documentation, assurez-vous que les champs obligatoires sont en place. Collez votre document ci-dessus : l’outil confirme le champ de version, info.title, info.version et paths, et liste ce qui manque.

Comment contrôler les champs obligatoires

  1. 1

    Collez le document

    Collez votre spec au format JSON ou YAML, même si elle est encore en cours de rédaction.

  2. 2

    Lancez le contrôle

    Passez à l'étape des résultats. Chaque champ manquant apparaît comme une erreur distincte.

  3. 3

    Ajoutez ce qui manque

    Ajoutez à votre fichier les champs listés en utilisant les extraits ci-dessous.

  4. 4

    Vérifiez à nouveau

    Collez la spec mise à jour et relancez le contrôle jusqu'à ce qu'aucune erreur ne s'affiche.

Les quatre éléments obligatoires

Champ Où le placer Exemple
Champ de version Premier niveau openapi: 3.0.3 ou swagger: "2.0"
info.title Dans info title: Orders API
info.version Dans info version: 1.0.0
paths Premier niveau paths: avec au moins votre première route

La valeur de info.version est la version de votre propre API, et non celle de la spécification OpenAPI. On l’oublie souvent, car la version de la spécification figure déjà en haut du document.

Un exemple concret où tout manque

servers:
  - url: https://api.example.com

Ce document minuscule ne contient aucun des éléments obligatoires. Le rapport liste trois erreurs :

Constat Type
Champ de version ‘openapi’ ou ‘swagger’ manquant. Erreur
Objet ‘info’ manquant. Erreur
Objet ‘paths’ manquant. Erreur

Lorsque l’objet info entier est absent, l’outil signale cette seule erreur et ne liste pas séparément le titre et la version. Ajoutez info avec ses deux champs, et la prochaine exécution signalera ceux qui manquent encore.

Squelette de départ

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Ce squelette passe tous les contrôles de champs obligatoires. Remplacez les noms par les vôtres et développez à partir de là. Les réponses, les schémas et la sécurité ne font pas partie de ce contrôle.

Quand lancer ce contrôle

Lancez-le lorsque vous démarrez une spec à partir de zéro, après l’avoir générée à partir du code, et avant de l’envoyer à quelqu’un qui l’importera dans un autre outil. De nombreux importeurs s’arrêtent au premier champ obligatoire manquant avec un message court : tout détecter en une seule passe évite plusieurs allers-retours. C’est aussi un rappel utile pour les débutants, qui oublient souvent info.version ou omettent paths pendant qu’ils esquissent une API.

Une fois les champs obligatoires validés, les ajouts utiles suivants sont une courte description sous info, une entrée servers et un operationId sur chaque opération. Rien de tout cela n’est contrôlé ici, mais cela rend la spec plus lisible et plus facile à transformer en code client.

Questions fréquentes

Non. Le champ openapi indique la version de la spécification utilisée. info.version est la version de votre propre API, par exemple 1.0.0.

La clé doit exister sous forme d’objet, et ce contrôle n’exige aucune route à l’intérieur. Ajoutez de vraies routes avant de publier.

Les contrôles du titre et de la version ne s’exécutent que si l’objet info existe. Ajoutez-le, puis relancez le contrôle pour voir si ses champs sont complets.

Non. Seuls le champ de version, info, title, version et paths sont exigés ici. Les détails au niveau des opérations ne sont pas examinés.

Outils similaires

Convertisseur de taille de fichier

Convertissez entre octets, Ko, Mo, Go, To et les unités binaires IEC (Kio, Mio, Gio, Tio), en combinant décimal et binaire comme vous le souhaitez.

Générateur de numéros de téléphone fictifs

Générez jusqu’à 50 numéros fictifs issus de plages officielles réservées dans cinq pays.

Générateur de lettres aléatoires

Générez des lettres A-Z aléatoires. Choisissez le nombre, les majuscules, les minuscules ou le mélange, puis utilisez le résultat pour des jeux ou la classe.

Générateur de Vagues SVG

Générez un séparateur en vague SVG fluide pour en-têtes et pieds de page, avec amplitude, fréquence, couleur et position haut ou bas réglables. Copiez le code SVG.

Validateur XSD

Validez un document XML par rapport à un schéma XSD et signalez les incohérences d'éléments et de types avec des numéros de ligne exacts.

Générateur de flèches CSS

Créez localement une flèche CSS avec direction, couleur, taille et épaisseur de bordure, puis copiez la règle.

Outil disponible dans d’autres langues

Guides et cas d'usage