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

#vscode #redoc #json #devportal

Publié le 27 janvier 2022 par Andrew Owen (4 minutes)

Dans cette série en 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 première partie ici et la troisième partie ici.

Partie II: Outils

Lorsque j’ai écrit la version originale de ce guide, j’étais rédacteur d’API et je créais des documents pour une solution de commerce électronique pilotée par les événements. L’architecture événementielle (EDA) est un sujet dont je parlerai plus en détail dans un prochain article. Le développement se faisait principalement en .NET et les documents de l’API étaient générés à l’aide de Swashbuckle (également un bon sujet pour un futur article). C’est ce qu’on appelle l’approche code first ou bottom up. Plus votre code grandit, plus il est difficile de maintenir des API cohérentes avec cette approche.

À mon avis, vous devriez créer votre spécification d’API et coder en fonction de celle-ci. Mais pour les besoins de ce guide, je supposerai que vous n’avez rien à dire à ce sujet et que vous devez simplement mettre la documentation de l’API entre les mains des développeurs. Il se peut que vous n’ayez même pas de schéma d’API, auquel cas vous devriez en créer un dans Postman, en vous basant sur la documentation de l’API dont vous disposez.

IDE

Visual Studio Code

Si vous utilisez Windows et que vous écrivez les documents de l’API directement dans le code, vous utilisez peut-être Visual Studio. Si vous n’utilisez pas Windows, la meilleure solution est Visual Studio Code.

Avant de configurer votre environnement de développement, assurez-vous d’avoir installé les outils CLI.

Configurer un environnement de développement .NET

Téléchargez et installez l’éditeur Visual Studio Code.
Téléchargez et installez le .NET Core SDK.
Créez un dossier appelé development dans lequel vous souhaitez stocker vos dépôts locaux.
Dans BitBucket Server, allez dans le référentiel avec lequel vous voulez travailler et cliquez sur l’icône de clonage dans la barre d’outils de gauche.
Copiez l’adresse HTTP.
Dans PowerShell / Terminal, naviguez jusqu’au dossier development.
Entrez git clone et collez l’adresse HTTP pour compléter la ligne.

Construire le fichier JSON OpenAPI 2.0 (Swagger)

Ceci suppose que vous avez un environnement de développement .NET fonctionnel et que vous avez correctement configuré Swashbuckle:

Dans PowerShell / Terminal, naviguez jusqu’au dossier src dans votre dépôt local.
Entrez dotnet build.
Naviguez vers le dossier où la DLL a été construite et entrez dotnet run.
Dans Chrome, naviguez jusqu’à l’URL indiquée dans la sortie de la compilation. Example: http://127.0.0.1:5000.
Cliquez sur le lien /swagger/v1/swagger.json pour télécharger le fichier JSON.

Plug-ins

Voici quelques plug-ins recommandés pour Visual Studio Code:

Better TOML par bungcip
C/C++ par Microsoft
C# par Microsoft
Code Spell Checker par Street Side Software
GitLens par Eric Amodio
Markdown Preview Enhanced par Yiyi Wang
Prettier - Formateur de code par Esben Petersen

Changements dans la documentation de l’API de prévisualisation

Exigences

Vous pouvez créer des tâches pour automatiser des processus dans Visual Studio Code.
Chaque dépôt nécessite son propre ensemble de tâches.
Vous devez ajouter .vscode/ au fichier .gitignore de tout référentiel avec lequel vous avez l’intention d’utiliser des tâches.
Des scripts séparés sont nécessaires pour macOS et Windows.

Convertir Swagger JSON en ReDoc HTML

Entrez: redoc-cli bundle <filename>.json.

Exécution des scripts

Après avoir configuré les scripts pour un dépôt donné, vous pouvez les exécuter à partir de Visual Studio Code.
Appuyez sur command+shift+B (macOS) ou ctrl+shift+B (Windows) pour lancer la tâche de construction.
Le fichier ReDoc HTML est ouvert dans Chrome.
Si le serveur met du temps à démarrer, la tâche ReDoc échouera. Une fois le serveur démarré, exécutez la tâche ReDoc à partir du menu Terminal.

Exemple Visual Studio Code tâches fichier JSON

Ce fichier doit être placé dans le dossier .vscode du dépôt Git et .vscode ajouté au fichier .gitignore.

tasks.json

    {
      "version": "2.0.0",
      "tasks": [
        {
          "label": "build",
          "command": "dotnet",
          "type": "process",
          "args": [
            "build",
            "${workspaceFolder}/src/Dev.Example.Com.Myproject/Devg.Example.Com.Myproject.csproj"
            ],
            "problemMatcher": "$msCompile"
          },
          {
            "label": "Swagger",
            "type": "shell",
            "command": ".vscode/swagger.sh",
            "windows": {
            "command": ".vscode\\swagger.cmd"
          },
          "presentation": {
            "reveal": "always",
            "panel": "new"
          }
        },
        {
          "label": "ReDoc",
          "type": "shell",
          "command": ".vscode/redoc.sh",
          "windows": {
            "command": ".vscode\\redoc.cmd"
          },
          "presentation": {
            "reveal": "always",
            "panel": "new"
          },
         "problemMatcher": []
       },
       {
          "label": "Build API Docs",
          "dependsOn": ["Swagger
  - ReDoc"],
          "group": {
            "kind": "build",
            "isDefault": true
          },
        }
      ]
    }

Exemples de scripts (macOS)

redoc.sh

    cd ~/
    rm redoc.jsonrm redoc-static.html
    
    # wait for server to start
    echo waiting for service to start
    sleep 10
    
    curl -o redoc.json http://localhost:62512/swagger/v1/swagger.json
    redoc-cli bundle redoc.json
    open -a "Google Chrome" redoc-static.html

swagger.sh

    export CONSUL=[http://consul.dev.example.com](http://consul.dev.example.com "http://consul.dev.example.com")
    cd src
    dotnet build --source [http://dev.example.com/myproject/](http://dev.example.com/myproject/ "http://dev.example.com/myproject/")
    cd Dev.Example.Com.Myproject
    dotnet run --urls=http://localhost:62512

Exemples de scripts (Windows)

redoc.cmd

    cd ~/
    del redoc.json
    del redoc-static.html
    
    # wait for server to start
    echo waiting for service to start
    sleep 10
    
    curl -o redoc.json

swagger.cmd

    set CONSUL=http://consul.dev.example.com
    cd src
    dotnet build --source http://dev.example.com/myproject/
    cd Dev.Example.Com.Myproject
    dotnet run --urls=http://localhost:62512