Apidog est une plateforme de collaboration et de gestion d'API qui prend en charge l'importation de spécifications d'API dans de nombreux formats. Elle peut importer directement presque tous les formats de spécifications d'API courants, y compris OpenAPI/Swagger, les collections Postman, les fichiers HAR et les commandes cURL.
Cependant, dans de nombreux projets réels, le principal défi ne concerne pas la manière d'importer des spécifications d'API, mais plutôt l'absence de spécifications d'API disponibles à importer. Certains systèmes plus anciens ou hérités n'ont jamais maintenu de documentation API et ne possèdent pas de fichiers OpenAPI ou Swagger.
Dans ces cas, si vous avez besoin de reconstruire rapidement la documentation API manquante ou de créer des cas de test afin que les testeurs puissent travailler avec des données réelles, l'utilisation d'un outil de capture de paquets est souvent l'approche la plus rapide.
En capturant le trafic HTTP/HTTPS de l'application, en filtrant les requêtes utiles, en les exportant au format HAR ou cURL, puis en les important dans Apidog, vous pouvez rapidement générer de la documentation API et jeter les bases de tests API ultérieurs.
De nombreux outils sont disponibles pour l'enregistrement du trafic. Cet article utilise Charles Proxy comme exemple pour démontrer les opérations spécifiques impliquées, mais vous pouvez également utiliser des alternatives telles que Proxyman, Fiddler ou les outils de développement intégrés à votre navigateur pour la capture de paquets. Le workflow de base est essentiellement le même pour tous ces outils.
Installation et configuration de base de Charles
Charles offre un essai gratuit de 30 jours. Vous pouvez télécharger la dernière version depuis le site officiel et l'installer sur votre système.
Lorsque vous lancez Charles pour la première fois, il peut vous demander si vous souhaitez configurer automatiquement les paramètres réseau. Il est recommandé de sélectionner "Grant Privileges" (Accorder les privilèges) pour accorder les autorisations nécessaires. Cela permet à Charles de capturer automatiquement le trafic HTTP de votre système.
Installation du certificat racine de Charles pour la capture HTTPS
Pour capturer le trafic HTTPS, vous devez installer le certificat racine de Charles. Cette étape est essentielle car la plupart des API modernes utilisent HTTPS.
Sur macOS :
- Cliquez sur "Help → SSL Proxying → Install Charles Root Certificate" (Aide → Proxy SSL → Installer le certificat racine de Charles) dans la barre de menu
- L'application "Accès au trousseau" s'ouvrira automatiquement
- Recherchez et localisez le certificat Charles Proxy
- Double-cliquez dessus et modifiez le paramètre de confiance en "Always Trust" (Toujours faire confiance)
Sur Windows :
- Cliquez sur "Help → SSL Proxying → Install Charles Root Certificate" (Aide → Proxy SSL → Installer le certificat racine de Charles) dans la barre de menu
- Pendant le processus d'installation, installez le certificat dans le magasin "Autorités de certification racines de confiance"
Activation du proxy SSL
Une fois le certificat installé, vous devez activer le proxy SSL :
- Sélectionnez Proxy → SSL Proxying Settings dans la barre de menu de Charles
- Cochez l'option "Enable SSL Proxying" (Activer le proxy SSL)
3. Ajoutez les noms de domaine (Host) et les ports (Port 443) que vous souhaitez capturer à la liste
4. Vous pouvez également utiliser * pour surveiller tous les domaines
Une fois la configuration terminée, Charles peut capturer les requêtes et réponses HTTP/HTTPS complètes.
Conseil : Si vous ne savez pas quels domaines votre application utilise, vous pouvez d'abord faire fonctionner l'application librement, puis observer les requêtes sous "Encrypted" (Chiffrées) dans la liste de session de Charles. Notez les domaines correspondants et ajoutez-les ensuite aux paramètres de proxy SSL de Charles.
Enregistrement du trafic API depuis votre application
Lancez l'application ou la page web que vous souhaitez analyser et interagissez avec diverses fonctionnalités, telles que la connexion, la consultation de données, la soumission de formulaires ou le téléchargement de fichiers. L'arborescence de session sur le côté gauche de Charles se mettra à jour en temps réel, regroupant les requêtes par domaine et URL.
Lorsque vous sélectionnez une requête spécifique, le panneau de droite affiche les informations de base et le contenu de la réponse de cette requête. Dans l'onglet Contenu, les réponses JSON et autres sont réduites en une structure arborescente, ce qui facilite la compréhension rapide de la structure des données et des champs.
Filtrage et exportation des points d'API
Une fois l'enregistrement terminé, vous constaterez peut-être qu'un grand nombre de requêtes ont été capturées. En plus des appels API réels, il y a diverses requêtes de ressources statiques, des appels de services tiers et d'autres trafics réseau. À ce stade, vous devez filtrer et ne conserver que les points d'API qui vous intéressent.
Options de filtrage
Concentrez-vous sur des domaines ou chemins spécifiques :
- Faites un clic droit sur un domaine ou un chemin et sélectionnez "Focus" (Focaliser)
- Charles ne conservera que les requêtes sous ce nœud, ce qui facilite votre analyse
Supprimez les requêtes non pertinentes :
- Faites un clic droit sur les requêtes non pertinentes et sélectionnez "Clear" (Effacer) pour les supprimer
- Ou sélectionnez plusieurs requêtes et supprimez-les en masse
Gérez les problèmes de mise en cache :
- Si la mise en cache empêche l'affichage correct du HTML ou du JSON, faites un clic droit et sélectionnez "No Caching" (Pas de mise en cache)
- Cela oblige Charles à ignorer la mise en cache lors des requêtes ultérieures, vous permettant de capturer le contenu complet de la réponse
Exportation en fichier HAR
Une fois le filtrage terminé, exportez vos sessions sélectionnées :
- Sélectionnez les sessions que vous souhaitez exporter :
Vous pouvez sélectionner un nœud de domaine entier, ou
Maintenez Cmd (Mac) ou Ctrl (Windows) et sélectionnez des requêtes spécifiques individuellement
Sélectionnez File → Export Session (Fichier → Exporter la session) dans la barre de menu
Dans la boîte de dialogue d'exportation, choisissez d'exporter au format "HTTP Archive (.har)" pour créer un fichier HAR
Importation dans Apidog pour générer automatiquement la documentation API
Il est maintenant temps d'importer votre trafic capturé dans Apidog :
- Ouvrez le client Apidog
2. Allez dans Project Settings → Import Data → .har File (Paramètres du projet → Importer des données → Fichier .har)
3. Sélectionnez le fichier HAR que vous avez exporté depuis Charles
Apidog analysera automatiquement le contenu du fichier et affichera les informations des points d'API détectés dans la zone de prévisualisation, y compris :
- Le nombre de points d'API détectés
- Les méthodes de requête (GET, POST, PUT, DELETE, etc.)
Pendant le processus d'importation, vous pouvez configurer des options telles que :
- Le module dans lequel importer
- Si vous souhaitez écraser les points d'API existants
Une fois l'importation terminée, vous pouvez visualiser les points d'API dans le module correspondant.
Affiner et optimiser la documentation API
La documentation API auto-générée est un excellent point de départ, mais elle nécessite généralement des ajustements supplémentaires pour répondre à vos exigences métier. Voici quelques améliorations courantes :
- Améliorer les noms des points d'API : Changez les noms génériques par des noms plus descriptifs
- Ajouter des descriptions de paramètres : Documentez ce que fait chaque paramètre et quand l'utiliser
- Affiner les composants de réponse : Organisez les composants de réponse pour qu'ils correspondent à votre logique métier
- Ajouter des exemples : Incluez des exemples de requêtes et de réponses
- Configurer l'authentification : Si un point d'API nécessite une authentification, configurez les informations correspondantes dans les variables d'environnement ou les paramètres d'authentification d'Apidog. Cela garantit que vos appels API fonctionnent correctement lors des tests.
En conclusion
En enregistrant le trafic HTTP/HTTPS à l'aide d'outils de capture de paquets, puis en l'important dans Apidog, vous pouvez rapidement générer de la documentation API et fournir un support de données réelles pour les tests.
Qu'il s'agisse d'un navigateur, d'un client de bureau ou d'une application mobile, cette méthode peut réduire considérablement le temps passé à préparer la documentation API et permettre à votre équipe de démarrer rapidement les tests et le développement d'API.