How to Update AWS Documentation and Publish it on ApiDog

---

1. Prérequis

Assurez-vous d'avoir bien déployé tous vos services sur AWS et que votre documentation est à jour !

2. Générer la documentation

1. Rendez-vous sur AWS Console
2. Dirigez vous dans le service API Gateway
3. Une fois sur le service API Gateway, sélectionnez l'api dont vous voulez générer la documentation (ex: Oskare)
4. Dans le menu de gauche, cliquez sur Documentation
5. En haut à droite, cliquez sur Publish documentation
6. Un menu va apparaître devant vous, sélectionnez le stage dont vous souhaitez générer la doc, précisez la version et cliquez sur Publish
7. Si les informations sont correctes, vous devrez voir un message en vert en haut de la page, et un bouton en haut à droite avec marqué Download documentation. Cliquez dessus pour télécharger la documentation
8. Une fois le téléchargement terminé, veuillez renommer le fichier téléchargé en (stage)-swagger.json (ex: dev-swagger.json)

3. Mettre à jour la documentation sur le répertoire

1. Rendez-vous dans le dossier documentation du projet, puis ensuite dans le dossier api-docs
2. Supprimez l'ancien fichier de documentation (ex: dev-swagger.json)
3. Glissez le nouveau fichier de documentation (ex: dev-swagger.json) dans le dossier api-docs

4. Mettre à jour le fichier pour le rendre compatible avec ApiDog

1. Rendez-vous dans le dossier scripts à la racine du répertoire
2. Exécutez la commande suivante : ts-node parse-documentation.ts (stage) (ex: ts-node parse-documentation.ts dev)
3. Un nouveau fichier sera généré dans le dossier scripts, nommé (stage)-swagger-parsed.json (ex: dev-swagger-parsed.json)

5. Ajouter la documentation sur ApiDog

1. Une fois sur le projet ApiDog, cliquez sur le bouton + situé sur la barre de navigation en haut.
2. Une page va s'ouvrir vous proposant 4 options, et un bouton More situé en bas des 4 autres boutons. Cliquez dessus et sélectionnez Import
3. Une nouvelle page va s'ouvrir, vous demandant de sélectionner un fichier. Glissez ou sélectionner le dossier sur le bouton de gauche
4. Un menu va apparaître proposant d'importer les routes, les schémas et les environnements.
   • Pour les routes, cliquez sur Folder, New folder et nommez le dossier avec la version suivante de l'API (ex: v1)
   • Pour les schémas, vérifiez qu'ils soient tous sélectionnés
   • De même pour les environnements
5. Une fois que vous avez tout selectionné, cliquez sur Confirm en bas à droite

6. Publier la documentation

1. Sur le menu à gauche, cliquez sur Share Docs, et sur New + en haut à droite
2. Remplissez le titre de la documentation, précisez son environnement (pour l'url ainsi que les variables d'environnement)
3. Cochez Base URL
4. Très important !! Cliquez sur Security et sélectionnez Password Required
5. Une fois ceci, faites Save