Validation des spécifications d’API dans Aperçus des API

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 4 minutes de lecture

    • Vous pouvez accéder aux règles de validation des spécifications d’API pour vérifier que vos spécifications d’API sont complètes, cohérentes et conformes aux bonnes pratiques.

    Les règles de validation identifient les problèmes structurels dès le début de l’importation ou de l’analyse, améliorant ainsi la qualité globale de l’API. Vous pouvez gérer ces règles pour appliquer la standardisation entre les spécifications d’API et réduire les erreurs en recherchant les champs manquants ou incorrects avant la publication ou l’utilisation des API en production.

    Stockage des spécifications d’API

    La table Spécification d’API [sn_api_insights_ws_api_specification] stocke les documents de spécification qui décrivent les API individuelles. Chaque enregistrement comprend les détails suivants pour identifier l’API à laquelle la spécification appartient et pour gérer plusieurs versions.
    Tableau 1. Détails de spécification d’API
    Champ Description
    Nom Nom de l’API.
    Version Version de l'API.
    Type Format et version de la norme de spécification de l’API utilisée. Par exemple, openapi3.0.0 pour une spécification OpenAPI.
    État État actuel indiquant si la spécification de l’API a été validée par rapport aux règles applicables et le résultat de la validation. Les valeurs valides sont :
    • Non traité : indique que la spécification de l’API n’a pas été validée.
    • Valide : indique que la spécification de l’API a été validée et traitée avec succès ou avec des avertissements. Si des avertissements sont présents, les détails sont affichés dans le champ Message .
    • Non valide : indique que la spécification de l’API a été validée, mais contient des erreurs. Les détails de l’erreur sont affichés dans le champ Message .
    Spécification Contenu complet du fichier de spécification d’API.
    Remarque :
    Pour OpenAPI, inclut le document OpenAPI complet décrivant les points de terminaison, les méthodes et le schéma.
    Message Les messages sont générés après le traitement de toutes les règles de validation pour le type de spécification. Ils comprennent des erreurs ou des avertissements avec des explications.

    Structure de la règle de validation

    La table Règle de validation des spécifications [sn_api_insights_ws_spec_validation_rule] stocke les règles de validation des spécifications d’API définies dans la table Spécification d’API [sn_api_insights_ws_api_specification].
    Remarque :
    Le rôle sn_cmdb_editor est requis pour modifier ou supprimer les règles de validation, et le rôle cmdb_read pour les afficher.

    Chaque règle de validation contient les composants clés suivants :

    Tableau 2. Composants de règle de validation
    Composant Description
    Spécification Spécification d’API pour laquelle la règle est conçue.
    Version Version de la spécification d’API validée par la règle. Si elle est spécifiée, la règle ne s’applique qu’à ces versions. Pour limiter la validation à des versions spécifiques, spécifiez-les dans le champ Version . Séparez les valeurs multiples par des virgules. Par exemple, 1.0,1.1,2.0.
    Remarque :
    Si le champ Version est laissé vide, la règle s’exécute pour toutes les versions installées du type de spécification d’API spécifié.
    Type Type de validation à effectuer. Les valeurs valides sont :
    • Chemin d’accès : vérifie que les clés spécifiques sont présentes dans des tableaux d’objets, des objets individuels ou les deux, dans les sections désignées du document de spécification de l’API.
    • Valeur attendue : valide si la clé spécifiée correspond aux valeurs attendues spécifiées dans le champ Valeur . Cette validation ne s’applique qu’à une seule clé spécifiée dans le champ Clé .
    Clé Partie de la spécification à vérifier. Si aucune valeur attendue n’est fournie, vous pouvez saisir plusieurs clés dans le champ Clé , séparées par des virgules.
    Valeur Valeurs attendues pour la clé spécifiée dans le champ Clé . Séparez les valeurs multiples par des virgules.
    Gravité Niveau de gravité du résultat de la règle de validation, soit un avertissement, soit une erreur.
    Remarque :
    Lorsqu’elle est définie sur avertissement, la spécification de l’API reste valide si la règle n’est pas respectée, indiquant qu’il ne s’agit pas d’un échec, et seul un message est affiché.
    Message Explication du problème lorsque la règle est déclenchée.
    Actif Option permettant d’activer la règle. Seules les règles actives sont déclenchées par la API Specification Validation tâche planifiée.

    Processus de validation des spécifications d’API

    La API Specification Validation tâche planifiée valide automatiquement les spécifications d’API non traitées par rapport aux règles actives en fonction de leur type de spécification pour garantir la conformité aux normes requises.

    Le processus de validation comprend les éléments suivants :
    1. Récupération de toutes les règles de validation actives à partir de la table Règle de validation des spécifications [sn_api_insights_ws_spec_validation_rule].
    2. La sélection d’API est marquée comme non traitée dans la table Spécification d’API [sn_api_insights_ws_api_specification].
    3. Application de règles de validation pertinentes à chaque API sélectionnée en fonction de son type de spécification, telle qu’OpenAPI.
    4. Vérification de la présence ou de l’exactitude de champs spécifiques ou de leurs valeurs dans la spécification d’API
    5. Mise à jour de l’état de traitement et capture des erreurs ou avertissements éventuels

    Règles prédéfinies pour les spécifications OpenAPI

    Par défaut, l’application inclut les règles de validation suivantes pour les spécifications OpenAPI :
    Valider les balises
    Vérifie que chaque balise de la spécification de l’API inclut un champ de nom . Si le champ Nom est manquant, le système renvoie un message d’avertissement mais marque la spécification comme valide.
    Valider les sections requises
    Vérifie que la spécification d’API inclut les sections de niveau supérieur requises : informations, chemins d’accès et composants. Si l’une de ces sections est manquante, le système renvoie un message d’erreur et marque la spécification comme non valide.
    Valider la section Serveurs
    Vérifie si la spécification de l’API inclut une section Serveurs qui définit les points de terminaison du serveur. Si la section serveurs est manquante, le système renvoie un message d’erreur et marque la spécification comme non valide.

    Ces règles prédéfinies vérifient les sections critiques telles que le balisage, les métadonnées et les définitions de serveur dans les spécifications OpenAPI.