Documenter les APIs avec Swagger (3/4) — Mise en scène de l’ensemble [FRENCH]

Dans cette série d’articles, je vais introduire les différents outils de Swagger. Swagger est un outil très pratique de documentation des APIs. Il permet de générer de la documentation “vivante”, permettant ainsi que la documentation soit toujours à jour, ce qui est très difficile à réaliser sans ce genre d’outil. Il permet également de générer du code automatiquement, permettant au développeur de se concentrer sur le coeur de son activité. Enfin, il repose sur un format de spécifications open source.

Cet article est donc décomposé en quatre parties :

  • Introduction,
  • Le framework Swagger,
  • La mise en scène de l’ensemble,
  • Le test de l’API.

Il y a deux manières d’utiliser la documentation :

  • soit par Swagger UI embarqué dans le serveur,
  • soit par Swagger UI tournant en autonome.

Utilisation de Swagger UI embarqué dans le serveur

Mise en place de l’environnement

docker run \
    --rm \
    -v ${PWD}:/local \
    swaggerapi/swagger-codegen-cli \
    generate -i /local/swagger.yaml -l nodejs-server -o /local/out

Le résultat de la commande est :

[main] INFO io.swagger.parser.Swagger20Parser - reading from /local/swagger.yaml
[main] INFO io.swagger.codegen.DefaultCodegen - Skipped overwriting index.js as the file already exists in /local/out//index.js
[main] INFO io.swagger.codegen.DefaultCodegen - Skipped overwriting package.json as the file already exists in /local/out//package.json
[main] INFO io.swagger.codegen.DefaultCodegen - Skipped overwriting README.md as the file already exists in /local/out//README.md
[main] WARN io.swagger.codegen.languages.NodeJSServerCodegen - 'host' in the specification is empty or undefined. Default to http://localhost.
[main] WARN io.swagger.codegen.DefaultGenerator - 'host' not defined in the spec. Default to 'localhost'.
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/out/service/ContactService.js
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/out/controllers/Contact.js
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/out/utils/writer.js
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/out/api/swagger.yaml
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/out/.swagger-codegen/VERSION

Installer les dépendances :

cd out/
npm install

La sortie de la commande est :

npm WARN deprecated superagent@1.8.5: Please note that v5.0.1+ of superagent removes User-Agent header by default, therefore you may need to add it yourself (e.g. GitHub blocks requests without a User-Agent header).  This notice will go away with v5.0.2+ once it is released.
        ░░░░░░⸩ ⠹ install:methods: info lifecycle methods@1.1.2~install: m[0m
> core-js@2.6.9 postinstall /Users/brunodelb/devops/notebooks/documentation/Swagger/out/node_modules/core-js
> node scripts/postinstall || echo "ignore"
Thank you for using core-js ( https://github.com/zloirock/core-js ) for polyfilling JavaScript standard library!
The project needs your help! Please consider supporting of core-js on Open Collective or Patreon: 
> https://opencollective.com/core-js 
> https://www.patreon.com/zloirock 
Also, the author of core-js ( https://github.com/zloirock ) is looking for a good job -)
npm notice created a lockfile as package-lock.json. You should commit this file.[K
added 147 packages from 83 contributors and audited 401 packages in 4.223s
found 5 vulnerabilities (2 low, 2 moderate, 1 high)
  run `npm audit fix` to fix them, or `npm audit` for details

Lancer le serveur :

node index.js

NodeJS indique que le serveur tourne en spécifiant le port d’écoute :

Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

Vérification de la bonne installation du serveur

Vérifier que le serveur répond correctement :

  • Allez dans la documentation à l’adresse http://0.0.0.0:8080/docs.
  • Cliquez sur Contact.
  • Cliquez sur la route GET /contact.
  • Cliquez sur Try it out!.
  • Le cadre Response Body affiche no content : le résultat est vide.

C’est normal. Nous allons modifier le code source du serveur pour retourner des données.

Modification du serveur pour retourner des données

Arrêter le serveur NodeJS.

Editer le fichier ./out/service/ContactService.js et remplacer la ligne :

examples['application/json'] = "";

par :

examples['application/json'] = [
        {"id": 1, "name": "Toto"}
    ];

Relancer NoteJS :

node index.js

NodeJS confirme que le serveur est relancé :

Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

Vérification que le serveur retourne des données comme attendu

Vérifier que le serveur retourne bien des données :

  • Retournez à l’adresse http://0.0.0.0:8080/docs.
  • Rafraîchissez la page.
  • Cliquez sur Contact.
  • Cliquez sur la route GET /contact.
  • Cliquez sur Try it out!.
  • Le cadre Response Body affiche :
[
  {
    "name": "Toto"
  }
]

Swagger affiche donc bien les données que nous avons ajoutée dans l’API.

Utilisation de Swagger UI tournant en autonome

Ce scénario correspond au cas où le code source du serveur n’a pas été généré par Swagger Codegen CLI.

Nous avons déjà créé les spécifications. Vous devez avoir spécifié l’hôte avec son port ainsi que le schéma (HTTP ou HTTPS) dans les spécifications.

Lancer le serveur de l’API REST :

node index.js

Le résultat de la commande est :

Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

Lancer le serveur Swagger UI :

docker run \
    -d \
    -p 83:8080 \
    -e SWAGGER_JSON=/app/swagger.yaml \
    -v $PWD:/app \
    swaggerapi/swagger-ui

Le résultat de la commande est :

c5e469bd19e91578bee821a61d18d9dbaa5d5d58005a27c7c2836b0b8a867fa1

Vérification que l’appel d’API pour afficher la liste des contacts échoue

  • Allez dans la documentation à l’adresse http://0.0.0.0:83.
  • Cliquez sur la ligne Get the list of contacts.
  • Cliquez sur Try it out.
  • Cliquez sur Execute.

Un message d’erreur est affiché dans la console du navigateur Chrome : blocked by CORS policy.

Vous devez activer CORS dans le serveur NodeJS.

Activation de CORS dans le serveur NodeJS

Editez le fichier index.js et ajoutez le code suivant avant la ligne // Initialize the Swagger middleware :

app.use(function (req, res, next) {
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, PUT, PATCH, DELETE');
  res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With,content-type');
  res.setHeader('Access-Control-Allow-Credentials', true);
  next();
});

Exécutez à nouveau la requête dans Swagger : le message d’erreur dans le navigateur Web disparaît.

Le cadre Response Body affiche alors :

[
  {
    "name": "Toto"
  }
]

Le framework Swagger est basé sur OpenAPI Specification.

Les spécifications sont rédigées en YAML ou en JSON.

Swagger comprend plusieurs sous-projets répondant à un objectif bien précis :

  • Swagger Editor : pour éditer les fichiers de spécification au format YAML;
  • Swagger UI : pour afficher et exécuter les fichiers de spécification Swagger de manière interactive;
  • Swagger CodeGen : pour lire des fichiers de spécification et générer le code squelette du client et du serveur.

Comments

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×