Tester une API REST avec Swagger, Postman et Jenkins

Avec l'essor de l'IoT vient l'âge d'or des APIs (et de REST), pour ouvrir facilement et de manière universelle des services.

La gestion des APIs devient donc une affaire de pros et doit être de plus en plus rigoureuse. Nous allons voir comment maîtriser les évolutions d'une API à partir d'outils spécialisés.

Les basiques

Je pense qu'il n'est plus nécessaire de présenter Postman (extension Chrome pour tester une API) ni Jenkins (serveur d'intégration continue). Mais il est intéressant de voir comment les deux peuvent travailler ensemble pour devenir une suite de tests automatisée d'API, via l'utilitaire en ligne de commande Newman et cette très bonne documentation officielle.

Swagger, la documentation simple et efficace!

Le meilleur moyen de s'assurer de la cohérence d'une API reste une bonne documentation. Pour ce faire, il existe Swagger (et sa version en ligne SwaggerHub) qui est l'outil de référence en la matière. En effet, il est très simple d'écrire rapidement une documentation pertinente, avec qui plus est une présentation agréable :

Putting it all together

Maintenant, voyons comment combiner tout cela.

Avec Swagger, vous avez la possibilité de définir, en plus de vos URLs, le formalisme des objets métier que vous manipulez. Pour cela il faut utiliser la section "definitions". Par exemple :

paths:
...
definitions:
  Asset :
    type: object
    additionalProperties: false
    required: ['name','owner','type']
    properties :
      name: 
        type: string
        description: Nom de l'Asset.
      owner:
        type: string
        description: Propriétaire du Device (User / domaine métier)
      type:
        type: string
        description: Type de l'objet
  Zone :
    type: object
    additionalProperties: false
    required: ['name','geojson']
    properties :
      name: 
        type: string
        description: Nom de la Zone.
      geojson :
        type: object
        description: Géométrie au format GeoJSON
        properties:
          type:
            type: string
            description: Feature
          geometry:
            type: object
            properties:
              type:
                type: string
                description: Point
              coordinates:
                type: array
                description: tableau de points GPS
                items:
                  type: number
      country:
        type: string
        description: Pays de la Zone, issu du référentiel Country.

Parallèlement, il est possible dans les tests Postman de vérifier que le contenu d'une réponse correspond à un schéma particulier (via TinyValidator). Et surprise, le formalisme des "schémas" utilisés par Postman correspond parfaitement à celui de nos "definitions" Swagger! Cela vous donne des idées?? Alors allons-y!

Tout d'abord, nous allons récupérer notre définition Swagger en l'exportant au format JSON pour pouvoir l'utiliser avec Postman. Cependant, à l'heure actuelle, il n'est pas possible dans Postman de charger un fichier externe, autre qu'un fichier de données de tests. Donc nous allons devoir faire un copié/collé de notre définition dans Postman. Mais pour essayer de faire cela proprement, nous allons coller notre Swagger dans une variable d'environnement de Postman, afin qu'elle soit accessible dans tous les tests :

Ensuite, nous allons écrire un test de vérification de schéma qui va se baser sur la définition d'un de nos objets métier Swagger :

Comme vous le voyez, nous chargeons en JSON notre définition Swagger, puis définissons un schéma de type tableau d'Assets, en récupérant la définition des Assets avec swaggerJson.definitions.Asset. Et en plus c'est facile!

Maintenant, lors de l'exécution de votre requête, les tests seront lancés et la réponse sera validée en fonction du schéma indiqué! Il est important à ce stade de disposer d'une définition d'objet stricte, notamment via l'utilisation des propriétés Swagger additionalProperties:false et required: ['name','owner','type'], sans quoi n'importe quelle réponse passera la validation.

Vous pouvez même aller jusqu'à utiliser votre définition Swagger pour récupérer les URLs à tester. Pour cela, il faut utiliser la partie "Pre-request Script" de Postman et parcourir de la même façon notre Swagger :

Ici, nous définissons une variable d'environnement 'url' à l'aide des attributs 'host' et 'basePath' de Swagger. Cette variable est ensuite utilisée par Postman via la syntaxe {{url}} dans sa barre d'adresse.

Remarque :

Il est également possible d'importer directement la définition Swagger dans Postman (via le bouton Import) pour récupérer automatiquement toutes les URLs à tester. Cependant, si vous avez besoin de réimporter votre définition suite à des modifications, cela va écraser tout ce qui existe déjà, y compris les tests!.

Pour terminer, il ne vous reste plus qu'à mettre tout cela dans Jenkins, via l'export de votre collection et de l'environnement Postman que vous passerez en paramètres de Newman! Enjoy!

Fichier(s) joint(s) :