Importer depuis OpenAPI / Swagger

Si vous décrivez déjà votre API avec une spécification OpenAPI 3.x ou Swagger 2.0, vous n'avez pas à recréer chaque endpoint à la main dans LoadFocus. Importez la spécification et LoadFocus génère un moniteur d'API par opération, méthode, URL et une assertion de code de statut, en une seule étape.

JSON et YAML sont tous deux acceptés. Les checks sont créés dans votre équipe active et comptent dans les limites de votre offre, exactement comme si vous les aviez créés à la main.

Comment ça marche

1. Ouvrez API Monitoring et accédez à la liste des checks.
2. Cliquez sur Nouveau Moniteur, puis choisissez Importer OpenAPI dans le groupe Synthetic.
3. Choisissez Coller la spécification et collez le texte de la spécification, ou choisissez Depuis une URL et saisissez une adresse que LoadFocus récupère pour vous.
4. Réglez la Fréquence, décidez si Activer les checks importés maintenant est coché, et ne renseignez Remplacer l'URL de base que si votre spécification n'a pas de serveur.
5. Cliquez sur Importer. LoadFocus analyse la spécification et crée un check pour chaque opération.

Pour chaque opération, LoadFocus construit :

• l'URL de la requête à partir des servers de la spécification (OpenAPI 3) ou de schemes + host + basePath (Swagger 2), jointe au chemin de l'opération ;
• la méthode HTTP (GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS) ;
• une assertion de code de statut : le premier code de succès 2xx documenté lorsque la spécification en déclare un, sinon une vérification que le code de statut est inférieur à 400 ;
• un nom lisible à partir de l'operationId de l'opération (ou MÉTHODE /chemin).

Les paramètres de chemin comme /users/{id} sont remplis avec la valeur example, default ou la première valeur enum du paramètre lorsque la spécification en fournit une. Sinon, 1 est utilisé pour les paramètres entiers et numériques et le texte example pour les autres. Vérifiez ces checks après l'import pour qu'ils pointent vers une vraie ressource.

Chaque check importé s'exécute depuis un emplacement, US East (N. Virginia). Modifiez ensuite un check si vous voulez plus d'emplacements.

Source : coller ou URL

• Coller la spécification : copiez le contenu de votre openapi.json, openapi.yaml, swagger.json ou swagger.yaml dans le champ. Une spécification peut peser jusqu'à environ 5 Mo et décrire jusqu'à 500 opérations.
• Depuis une URL : saisissez l'adresse publique de votre spécification (par exemple https://api.example.com/openapi.json). L'adresse doit commencer par https://, les redirections ne sont pas suivies et les adresses internes ou privées sont refusées. La même limite de taille s'applique.

URL de base

LoadFocus lit l'URL de base depuis la spécification : la première entrée de servers pour OpenAPI 3, ou schemes, host et basePath pour Swagger 2. Si la spécification n'en déclare aucune (ou si son premier serveur est un chemin relatif), renseignez Remplacer l'URL de base, par exemple https://api.example.com. Le remplacement n'est qu'un repli : quand la spécification a un serveur utilisable, c'est lui qui est utilisé et le remplacement est ignoré. Pour importer vers un hôte de préproduction, placez-le en premier dans la liste servers de la spécification.

Fréquence et activation

• Fréquence : à quelle fréquence chaque check importé s'exécute. Choisissez 5, 10, 15 ou 30 minutes, ou 1 heure ; 5 minutes est la valeur par défaut.
• Activer (Activer les checks importés maintenant) : lorsqu'elle est cochée, les checks démarrent immédiatement. Décochez-la pour les importer en pause, les vérifier et n'activer que ceux que vous voulez. C'est utile lorsque votre spécification contient des opérations d'écriture (POST, PUT, DELETE) qu'un moniteur planifié ne doit pas appeler à répétition.

Ce qu'il faut vérifier après l'import

• Opérations d'écriture : un moniteur planifié appelle l'endpoint à chaque exécution. Pour POST, PUT, PATCH et DELETE, confirmez que vous voulez vraiment les surveiller, ou importez en pause et n'activez que celles qui sont sûres.
• Paramètres de chemin : assurez-vous que les valeurs substituées pointent vers une ressource existante.
• Authentification : les checks importés n'ont aucun en-tête. Ajoutez les en-têtes dont votre API a besoin, comme une clé d'API ou un jeton, via les variables et secrets pour que les endpoints authentifiés renvoient leur vrai statut.
• Corps de requête : pour une opération OpenAPI 3 dont le corps de requête a un exemple, cet exemple est envoyé comme corps. Dans tous les autres cas, y compris toutes les opérations Swagger 2, la requête est envoyée sans corps.

Limites de l'offre

Les checks importés comptent dans la limite de moniteurs d'API de votre offre, comme les checks que vous créez à la main. Si une spécification comporte plus d'opérations que votre quota restant, LoadFocus en crée autant que possible et indique combien ont été créés et combien ont été ignorés, de sorte que rien n'est créé silencieusement au-delà de votre offre.

Garder les moniteurs synchronisés

Un import ponctuel est un moyen rapide de démarrer. Si vous voulez que vos moniteurs restent alignés avec la définition de votre API au fil du temps, gérez-les comme des fichiers versionnés avec Monitoring as Code et réconciliez-les depuis la CI.