Créer un portail pour les développeurs sans budget (partie 1 de 3)

illustrations illustrations illustrations illustrations illustrations illustrations illustrations
post-thumb

Publié le 20 janvier 2022 par Andrew Owen (9 minutes)

Dans cette série de trois parties, je vais vous expliquer comment créer un portail de développement complet pour votre contenu Swagger ou OpenAPI 3.0 sans dépenser un centime. Vous pouvez lire la deuxième partie ici et la troisième partie ici.

Partie I: Backend

Un portail de développement est simplement un site web qui présente la documentation de l’API (et d’autres) aux développeurs. Il peut être aussi simple qu’une page web statique ou aussi complexe que vous le souhaitez. Dans cette série, nous utiliserons les technologies back-end suivantes:

  • Générateurs de sites statiques
  • Contrôle des sources
  • Conteneurisation
  • Automatisation

En outre, vous passerez inévitablement beaucoup de temps à utiliser un navigateur. Pour le meilleur et pour le pire, Chrome est la nouvelle norme.

Générateurs de sites statiques

Hugo

Hugo est un type de serveur web connu sous le nom de générateur de site statique (SSG). Il est léger et rapide et peut servir des contenus dynamiques et statiques. Vous pouvez tester le contenu localement avant de le déployer. Pour le contenu OpenAPI, nous utiliserons la version en ligne de commande de ReDoc pour convertir les fichiers JSON Swagger en une page HTML statique qui sera servie par Hugo.

Installer les outils CLI (macOS)
  1. Homebrew est un gestionnaire de paquets. Depuis le Terminal, entrez /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)".
  2. Git permet de contrôler les sources. Dans le Terminal, entrez git et suivez les instructions pour installer Xcode.
  3. Hugo est un générateur de sites statiques. Depuis le Terminal, entrez brew install hugo.
  4. NPM est un gestionnaire de paquets pour JavaScript. Depuis le Terminal, entrez brew install nodejs. ReDoc rend un fichier OpenAPI en une page HTML statique. Depuis le Terminal, entrez npm install -g redoc-cli@0.13.2. Vous pouvez omettre le @<numéro_de_version>, mais j’ai constaté que npm ne récupère pas toujours la dernière version si vous le faites. Assurez-vous que vous utilisez la version 0.9.8 ou une version plus récente: redoc-cli --version\.
  1. (Optionnel) Swagger2PDF convertit un fichier OpenAPI JSON en un document PDF statique. Depuis le Terminal, entrez npm install swagger-spec-to-pdf.
Installer les outils CLI (Windows)
Exigences
  • Powershell 3 (ou version ultérieure). Powershell 5 est déjà installé dans Windows 10.
  • .NET framework 4.5 (ou version ultérieure).
Instructions
  1. Téléchargez et installez Scoop.
  2. Git fournit le contrôle de source. Depuis PowerShell, entrez scoop install git.
  3. Hugo est un générateur de sites statiques. Depuis PowerShell, entrez scoop install hugo.
  4. NPM est un gestionnaire de paquets pour JavaScript. Depuis PowerShell, entrez scoop install nodejs.
  5. ReDoc rend un fichier OpenAPI dans une page HTML statique. Depuis PowerShell, entrez npm install -g redoc-cli0.13.2. Vous pouvez omettre le @<numéro de version>, mais j’ai constaté que npm ne récupère pas toujours la dernière version si vous le faites. Assurez-vous que vous utilisez la version 0.9.8 ou plus récente: redoc-cli --version.
  6. (Optionnel) Swagger2PDF convertit un fichier OpenAPI JSON en un document PDF statique. Depuis PowerShell, entrez npm install swagger-spec-to-pdf.
  7. cURL est un outil de transfert de données en ligne de commande. Depuis PowerShell, entrez scoop install curl.
Tester une copie locale du portail de développement

Naviguez vers le dossier où vous avez cloné le dépôt Git.

  1. Depuis la ligne de commande, entrez hugo server.
  2. Copiez l’URL de la sortie de la console et collez-la dans le navigateur Chrome.
Ajouter Google Analytics à une page HTML statique

Collez le texte suivant après la balise <head>:

    <!-- Global site tag (gtag.js) - Google Analytics --><script async src="https://www.googletagmanager.com/gtag/js? id=<yourID>"></script>

Contrôle à la source

Git

Si vous générez des commentaires à partir du code, vous travaillerez directement dans le dépôt du logiciel. Il s’agit généralement d’un dépôt Git. Vous devez vous familiariser avec les processus de création de branches, de création de demandes d’extraction, de résolution de conflits et de fusion de modifications. Il existe un certain nombre d’options d’hébergement commerciales, notamment GitHub, GitLab et Bitbucket. Nous nous intéresserons ici à Bitbucket.

Obtenir l’URL de Bitbucket
  1. Dans Chrome, naviguez vers le dépôt requis.
  2. Dans le menu de gauche, cliquez sur Clone.
  3. Copiez l’URL.
Cloner le référentiel et créer une branche locale
  1. Ouvrez PowerShell / Terminal et naviguez jusqu’au dossier de votre dépôt local. Exemple: ~/development/.
  2. Entrez git clone et collez le chemin que vous avez copié depuis Chrome. Cela crée une copie locale du dépôt.
  3. Dans Visual Studio Code, ouvrez le dossier du dépôt.
  4. Dans le coin inférieur gauche de la fenêtre, cliquez sur Branch.
  5. Saisissez un nom dans la boîte ( feature/apidocs-<nom de la classe API>) et sélectionnez la branche sur laquelle le baser. Exemple: development

Vous pouvez maintenant effectuer vos modifications.

Publier les modifications
  1. Dans Visual Studio Code, dans le menu de gauche, cliquez sur Contrôle de source.
  2. Saisissez une brève description de la raison pour laquelle vous avez effectué les modifications dans la boîte.
  3. Cliquez sur l’icône Commettre (coche). Si vous êtes invité à configurer Visual Studio Code pour qu’il mette automatiquement en scène les modifications, faites-le.
  4. Dans le coin inférieur gauche de la fenêtre, cliquez sur Publier les modifications.
Créer une demande d’extraction
  1. Dans Chrome, naviguez vers le tableau de bord Bitbucket.
  2. Dans le menu Dépôts, sélectionnez le dépôt avec lequel vous travaillez.
  3. Dans le menu de gauche, cliquez sur Créer une demande d’extraction.
  4. Sélectionnez votre dépôt local dans la liste Source.
  5. Confirmez le dépôt Destination (en général, développement) et cliquez sur Continuer.
  6. Saisissez une Description. Celle-ci doit contenir toute explication supplémentaire concernant la modification.
  7. Joignez une copie du fichier ReDoc HTML.
  8. Sélectionnez Reviseurs. En général, ce champ est pré-rempli. Vous pouvez commencer à taper un nom pour trouver un utilisateur. Assurez-vous que le propriétaire du produit est inclus.
  9. Cliquez sur Créer.

Vous recevrez des notifications par courriel lorsque le statut de la demande d’extraction changera. Exemple: Lorsque la modification est approuvée.

Résoudre les conflits
  1. Dans votre branche locale: git pull origin master.
  2. Fusionner les changements de code entrants tout en conservant les changements de documentation.
  3. git commit -am "<your commit message>"
  4. git push
Fusionner les modifications

Dans Chrome, naviguez jusqu’à la pull request et cliquez sur Merge.

Supprimer la branche
  1. Une fois que la modification a été fusionnée avec succès, dans le menu de gauche, cliquez sur Branches.

  2. Localisez la branche dans laquelle vous travailliez et dans le menu Actions, sélectionnez Supprimer

    branche.

  3. Cliquez sur Supprimer pour confirmer votre action.

Modifier le texte dans Bitbucket

Bien que cela ne soit pas directement lié aux API, il peut arriver que vous ayez à modifier du texte contenu dans un fichier d’un dépôt Git stocké dans Bitbucket. Vous devez disposer d’un compte Bitbucket pour modifier les fichiers.

  1. Naviguez jusqu’au fichier dans Bitbucket.
  2. Cliquez sur Editer.
  3. Effectuez vos modifications.
  4. Cliquez sur Commit.
  1. (Facultatif) Saisissez un titre dans la case Message de validation.
  1. Cochez la case Créer une demande d’extraction pour cette modification.
  2. Cliquez sur Commit.
  1. (Facultatif) Entrez un nom de branche. Exemple: feature/uitext.
  1. Cliquez sur Créer une demande d’extraction.
  2. Entrez une Description.
  3. Cliquez sur Créer.

Lorsque votre demande d’extraction a été examinée et qu’il y a eu au moins une compilation réussie, à condition qu’il n’y ait pas de conflit de fusion, vous pouvez fusionner votre changement.

  1. Naviguez vers les demandes d’extraction.
  2. Localisez votre demande d’extraction et cliquez sur son hyperlien.
  3. Cliquez sur Fusionner.

Si la fusion a réussi, vous devriez maintenant supprimer votre branche.

  1. Naviguez jusqu’aux branches.
  2. Cliquez sur le bouton Actions de votre branche et sélectionnez Supprimer la branche, puis cliquez sur Supprimer.

Suivi des problèmes

Suivre les tâches de documentation dans Jira
  • Les tâches de documentation autonomes doivent avoir le type d’enjeu Documentation.
  • Les tâches du développeur qui nécessitent de la documentation doivent avoir l’étiquette Documentation.
  • La documentation doit faire partie de la définition de done.

Containerization

Les conteneurs sont une technologie de virtualisation au niveau du système d’exploitation. Les Solaris Zones de Sun Microsystems ont été une des premières implémentations en 2004. Mais la technologie a été popularisée par les conteneurs Docker, publiés en 2013, et la gestion des conteneurs Kubernetes, publiée l’année suivante.

Vous n’avez pas besoin de conteneurisation si vous utilisez une solution d’hébergement telle que Netlify. Cependant, si vous hébergez votre propre site, vous devriez au moins envisager d’utiliser des conteneurs.

Installer Docker

Si vous déployez votre portail de développement dans un conteneur Docker, vous pouvez l’essayer localement avant de construire votre chaîne d’outils d’automatisation avec Docker Desktop.

Après l’installation, vous pouvez exécuter les images Docker localement. Exemple: docker run -d --name rabbitmq -p 15672:15672 -p 5672:5672 bitnami/rabbitmq:latest

Créer un fichier Docker pour Hugo

La façon la plus simple de déployer le site statique Hugo est dans une image Docker, telle que définie par un Dockerfile:

  • FROM définit l’image de base (dans l’exemple Alpine, une distribution Linux légère).
  • COPY copie les fichiers et les dossiers dans l’image Docker.
  • ARG spécifie les arguments pour la commande de construction de Docker.
  • RUN exécute les commandes.
  • EXPOSE informe l’utilisateur sur les ports utilisés.
  • CMD spécifie le composant et ses arguments à utiliser par l’image.

Voici un exemple:

    FROM alpine:3.8 as runner
    COPY . .
    ARG HUGO_VERSION=0.80.0
    RUN apk --no-cache add \ 
            curl \
            git \
        && curl -SL https://github.com/gohugoio/hugo/releases/download/v
    ${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz \
    		-o /tmp/hugo.tar.gz \
        && tar -xzf /tmp/hugo.tar.gz -C /tmp \
        && mv /tmp/hugo /usr/local/bin/ \
        && apk del curl \
        && rm -rf /tmp/*
    
    EXPOSE 80
    CMD hugo --renderToDisk=true --watch=true --port=80 --bind="0.0.0.0" --
    baseURL="${VIRTUAL_HOST}" server
Démarrer Docker à la connexion (macOS)

Certaines API peuvent nécessiter un middleware, par exemple une instance RabbitMQ locale. Il peut être pratique de demander à Docker de démarrer l’intergiciel lorsque vous vous connectez. Par exemple, sur macOS:

  1. Ouvrez l’application Automator.

  2. Sélectionnez le type Application et cliquez sur Choisir.

  3. Dans le menu Actions, sélectionnez Utilités > Exécuter un script Shell.

  4. Dans la section Exécuter un script Shell, sélectionnez /bin/bash dans le menu Shell.

  5. Dans la boîte, entrez:

    cd /usr/local/bin
    while (! ./docker stats --no-stream ); do
    sleep 10
    done
    ./docker start rabbitmq

  6. Dans le menu Fichier, cliquez sur Enregistrer.

  7. Naviguez jusqu’au dossier Applications (ou le dossier Applications de votre utilisateur).

  8. Saisissez StartRabbit dans la case Enregistrer sous et cliquez sur Enregistrer.

  9. Ouvrez Préférences système et cliquez sur Utilisateurs et groupes.

  10. Sélectionnez votre utilisateur et cliquez sur Éléments de connexion.

  11. Cliquez sur Ajouter (+).

  12. Naviguez jusqu’à l’emplacement où vous avez enregistré l’application StartRabbit et sélectionnez-la.

  13. Cliquez sur Ajouter.

  14. Fermez Préférences système.

Le script sera exécuté lors de la prochaine connexion. Le chemin doit être modifié car /usr/local/bin ne fait pas partie du chemin pour les scripts de démarrage. Le script attend que le démon Docker démarre avant de démarrer le conteneur RabbitMQ. Pour ce faire, il interroge Docker jusqu’à ce qu’il obtienne une réponse. Un rouage est affiché dans le menu de droite lorsque le script est en cours d’exécution.

Si vous déployez plus d’une instance Docker, c’est le moment idéal pour commencer à utiliser Kubernetes.

Automation

Vous devez automatiser vos déploiements afin que, lorsque votre code est modifié, la documentation de votre API soit mise à jour. Lorsque le logiciel est développé à l’aide de l’intégration et du déploiement continus, il est utile que les documents soient également déployés de cette manière. Une solution open source populaire pour cela est Jenkins. Mais si vous utilisez GitHub, vous pouvez utiliser GitHub Actions:

name: Build ReDoc HTML
on:
  push:
    paths:
    - 'static/apis/**.yaml'
  workflow_dispatch:
    jobs:
      redoc:
        runs-on: ubuntu-latest
        permissions:
          contents: write
        steps:
        - uses: actions/checkout@v4
        - name: Create local changes
          run: |
            npm i -g redoc-cli
            redoc-cli build static/apis/swagger.yaml -o static/apis/swagger.html            
        - name: Commit files
          run: |
            git config --local user.email "github-actions@users.noreply.github.com"
            git config --local user.name "github-actions"
            git add .
            git commit -a -m "Add changes"            
        - name: Push changes
          run: git push origin main