Si vous travaillez sur un projet qui implique la création d’une API pour un site Web existant, vous aurez besoin d’une spécification OpenAPI pour décrire l’API. Une spécification OpenAPI est un document décrivant les points de terminaison, les paramètres de demande et de réponse, les exigences d’authentification et d’autres détails de l’API. La création d’une spécification OpenAPI à partir de zéro peut prendre du temps, mais il existe des outils disponibles qui peuvent vous aider à en générer une rapidement et facilement.
Dans cet article de blog, nous allons vous montrer comment générer une spécification OpenAPI pour un site Web existant à l’aide de fichiers HTTP Archive (HAR), qui sont des enregistrements des interactions d’un navigateur Web avec un site Web.
Étape 1 : Collecter les points de terminaison de l’API
Avant de générer une spécification OpenAPI, vous devez collecter tous les points de terminaison d’API pour le site Web sur lequel vous travaillez. Pour ce faire, vous pouvez notamment utiliser les outils de développement intégrés du navigateur Chrome pour surveiller le trafic réseau et l’enregistrer en tant que fichier .har.
Voici comment utiliser Chrome pour collecter les points de terminaison de l’API ; J’utiliserai le site Web de Bitbucket pour ma démo.
- Ouvrez Chrome et accédez au site Web pour lequel vous souhaitez créer une spécification OpenAPI.
- Ouvrez les outils de développement Chrome en cliquant sur les trois points dans le coin supérieur droit de la fenêtre du navigateur et en sélectionnant « Plus d’outils »> « Outils de développement » ou en cliquant avec le bouton droit n’importe où sur la page et en sélectionnant « Inspecter » dans le menu contextuel.
- Dans la fenêtre des outils de développement qui apparaît, sélectionnez l’onglet « Réseau ».
- Sélectionnez le filtre « XHR » pour n’afficher que les requêtes API.
Actualisez la page pour commencer à capturer le trafic réseau.- Effectuez les actions sur le site Web qui déclenchent les appels d’API que vous souhaitez inclure dans la spécification.
- Dans le journal de trafic réseau, localisez les demandes d’API et cliquez dessus pour afficher leurs détails.
- Cliquez sur le bouton « Exporter » en haut du journal de trafic réseau et enregistrez le fichier en tant que fichier .har.
Étape 2 : Générer une spécification OpenAPI avec des outils
Il existe plusieurs outils disponibles qui peuvent vous aider à générer une spécification OpenAPI à partir du fichier .har que vous avez créé à l’étape 1. Nous utiliserons APIGit, une plate-forme Git pour le développement d’API, pour générer la spécification dans cet exemple.
Voici comment utiliser APIGit pour générer une spécification OpenAPI :
- Mais d’abord, allez sur APIGit et créez un compte gratuit si vous n’en avez pas déjà un.
- Une fois connecté, créez un nouveau référentiel pour votre spécification OpenAPI en cliquant sur le bouton « Créer un référentiel ».
- Nommez votre référentiel et donnez-lui une description.
- Sous l’onglet « API Specifications », cliquez sur le bouton « add or upload spec » et choisissez le fichier .har que vous avez créé à l’étape 1.
- Cliquez sur le bouton « Créer » et attendez qu’APIGit traite le fichier.
- Une fois le fichier traité, vous verrez une représentation visuelle de vos points de terminaison API.
Étape 3 : Répétez l’étape 1 pour collecter d’autres actions
Il est difficile de collecter toutes les API pour le site Web en même temps, vous devrez donc probablement répéter l’étape 1 pour différents cas d’utilisation. Par exemple, si vous travaillez avec Bitbucket, vous avez peut-être déjà collecté les API pour créer un référentiel et soumettre un commit. Maintenant, vous souhaiterez peut-être collecter les API pour créer une branche, faire une demande d’extraction, fusionner la demande d’extraction, etc.
Pour collecter des API pour ces cas d’utilisation supplémentaires, suivez le même processus qu’à l’étape 1. Ouvrez les outils de développement Chrome, accédez à la page appropriée sur le site Web, effectuez les actions qui déclenchent les appels d’API et enregistrez le trafic réseau en tant que fichier . fichier har.
Étape 4 : Importer un nouveau fichier .Har pour générer des API
Lorsque vous travaillez sur votre site Web, vous devrez peut-être collecter des API supplémentaires ou modifier celles qui existent déjà. Pour mettre à jour votre spécification OpenAPI avec ces modifications, vous pouvez importer un nouveau fichier .har dans APIGit et générer la description de l’API mise à jour.
Lors de l’importation d’un nouveau fichier .har, vous disposez de deux options pour gérer la duplication :
- Importez le fichier .har dans la spécification existante : APIGit détectera automatiquement toute API en double et n’en enregistrera qu’une seule copie. Pour ce faire, accédez à la spécification d’API actuelle et cliquez sur le bouton « Modifier » pour accéder à la page d’édition de l’API. Ensuite, cliquez sur le bouton « Importer » en haut et téléchargez le nouveau fichier .har.
- Importez le fichier .har dans une nouvelle spécification : si vous souhaitez conserver la spécification d’origine et la comparer avec la nouvelle pour voir ce qui a changé, vous pouvez créer une nouvelle spécification et utiliser la fonction diff pour comparer les modifications. Pour ce faire, suivez les mêmes étapes que celles décrites à l’étape 1, mais au lieu d’importer le fichier dans la spécification existante, cliquez sur le bouton « Ajouter ou télécharger une spécification » pour créer une nouvelle spécification. Vous pouvez ensuite utiliser la vue diff en cliquant sur le bouton « changer » pour comparer les changements entre les spécifications d’origine et mises à jour.
Étape 5 : répétition des étapes 3 et 4 jusqu’à ce que toutes les API soient collectées
La collecte de toutes les API d’un site Web peut prendre du temps, surtout si le site Web comporte de nombreuses fonctionnalités. Cela peut prendre plusieurs tours de navigation sur le site et de collecte de fichiers .har avant d’avoir toutes les API nécessaires pour votre spécification OpenAPI. Voici les étapes à répéter jusqu’à ce que vous ayez collecté toutes les API :
- Répétez l’étape 1 : utilisez les outils de développement Chrome pour parcourir le site Web et collecter des fichiers .har pour des cas d’utilisation supplémentaires.
- Répétez l’étape 2 : Générez une spécification OpenAPI mise à jour à l’aide des nouveaux fichiers .har. Encore une fois, n’oubliez pas de choisir l’option appropriée pour gérer la duplication lors de l’importation du nouveau fichier .har.
- Passez en revue la spécification mise à jour et apportez les modifications nécessaires pour garantir l’exactitude et l’exhaustivité.
- Répétez les étapes 1 à 3 si nécessaire jusqu’à ce que vous ayez collecté toutes les API nécessaires pour votre site Web.
Étape 6 : Compléter et améliorer vos API
Une fois que vous avez collecté toutes les API nécessaires et généré votre spécification OpenAPI à l’aide d’APIGit ou d’un autre outil, il est temps de revoir et d’améliorer la description de votre API.
Une spécification d’API complète doit inclure des descriptions détaillées de chaque API, des définitions de requête et de réponse, la validation des données et d’autres détails importants. Ensuite, avec la spécification générée automatiquement en main, vous pouvez commencer à apporter des modifications et à compléter les informations manquantes.
APIGit propose un éditeur OpenAPI intuitif qui peut vous aider à compléter vos API plus rapidement et plus facilement. Avec l’éditeur, vous pouvez facilement ajouter ou modifier des balises, des paramètres, des réponses et d’autres détails pour chaque API. Vous pouvez également valider votre définition d’API pour vous assurer qu’elle est conforme à la spécification OpenAPI.
En plus de compléter la définition de l’API, vous pouvez également améliorer vos API en ajoutant de la documentation et des exemples pour aider les autres développeurs à comprendre comment utiliser votre API. Cela peut inclure des didacticiels détaillés, des extraits de code et d’autres ressources qui permettent aux autres développeurs de démarrer plus facilement avec votre API.
En complétant et en améliorant vos API, vous pouvez vous assurer que la documentation de votre API est précise, complète et facile à utiliser. Cela aidera d’autres développeurs à travailler plus efficacement avec votre API et peut finalement conduire à plus d’adoption et de succès pour votre projet.