Validation des spécifications de l’API dans Aperçus des API
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 respectent les bonnes pratiques.
Les règles de validation identifient les problèmes structurels à un stade précoce 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 vérifiant les champs manquants ou incorrects avant que les API ne soient publiées ou utilisées en production.
Stockage des spécifications d’API
La table Spécification de l’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 permettant d’identifier l’API à laquelle appartient la spécification et de gérer plusieurs versions.
| 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 au résultat de la validation. Les valeurs valides sont :
|
| Spécification | Contenu complet du fichier de spécification de l’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 Spécification de validation de la spécification [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 de l’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 :
| Composant | Description |
|---|---|
| Spécification | Spécification de l’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 restreindre la validation à des versions spécifiques, spécifiez-les dans le champ Version . Séparez les valeurs 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 :
|
| 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 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 s’affiche. |
| Message | Explication du problème lorsque la règle est déclenchée. |
| Actives | 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 de la spécification de l’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 :
- Récupération de toutes les règles de validation actives à partir de la table Règle de validation de spécification [sn_api_insights_ws_spec_validation_rule].
- La sélection d’API marquées comme non traitées dans la table de spécification de l’API [sn_api_insights_ws_api_specification].
- Application des règles de validation pertinentes à chaque API sélectionnée en fonction de son type de spécification, telle qu’OpenAPI.
- Vérification de la présence ou de l’exactitude de champs spécifiques ou de leurs valeurs dans la spécification de l’API.
- Mise à jour de l’état du 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 dans la spécification de l’API inclut un champ
de nom. Si le champName (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 de l’API inclut les sections de niveau supérieur requises :
informations,chemins d’accèsetcomposants. Si l’une de ces sections est manquante, le système renvoie un message d’erreur et marque la spécification comme non valide. - Section Valider les serveurs
- Vérifie si la spécification de l’API inclut une section
serveursqui définit les points de terminaison du serveur. Si la sectionServeursest 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.