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.
Test de base de l’API
Pour tester l’implémentation des spécifications Swagger, vous pouvez utiliser Dredd (https://dredd.org).
Pour installer Dredd :
sudo npm install -g dredd --allow-root --unsafe-perm=true |
Lançons Dredd sur notre fichier de spécifications :
dredd swagger.yaml http://0.0.0.0:8080 --reporter html --reporter xunit |
Création d’un serveur Mock
Vous pouvez créer facilement un serveur Mock réaliste avec Prism.
Install Prism :
sudo npm install -g @stoplight/prism-cli |
Lançons le serveur de Mock :
prism mock swagger.yaml |
Tests avancés de l’API
Pour réaliser des tests avancés de l’API, nous allons utiliser :
- Mocha : c’est un framework de test en Javascript qui facilite le test asynchrone,
- Chai : c’est une library d’assertion mettant à disposition des méthodes assert, expect et should,
- SuperTest : c’est une library fournissant une abstraction de haut niveau pour le test de réponses de endpoints d’API NodeJS.
Installons ces trois bibliothèques :
npm install chai |
npm install supertest |
sudo npm install -g mocha |
Dans le répertoire du projet, créons un fichier de test :
cd out |
cat <<EOF> test.js |
var should = require('chai').should(), |
expect = require('chai').expect, |
supertest = require('supertest'), |
api = supertest('http://0.0.0.0:8080'); |
describe('Contact', function() { |
//before(function(done){ |
//}); |
it('should return a 200 response', function(done) { |
api.get('/contact') |
.set('Accept', 'application/json') |
.expect(200,done); |
} |
); |
it('should return at least an id and a name', function(done) { |
api.get('/contact') |
.set('Accept', 'application/json') |
.expect(200) |
.end(function(err, res) { |
expect(res.body[0]).to.have.property("id"); |
expect(res.body[0]).to.have.property("name"); |
expect(res.body[0].id).to.not.equal(null); |
expect(res.body[0].name).to.not.equal(null); |
done(); |
} |
); |
}); |
it('should return a 201 response', function(done) { |
api.post('/contact') |
.set('Accept', 'application/json') |
.expect(200,done); |
} |
); |
}); |
EOF |
Lançons maintenant les tests :
mocha |
Création d’une image Docker
Puisque que maintenant on va se connecter au serveur Web de l’API depuis le conteneur et non plus depuis l’hôte, vous devez modifier l’adresse IP de l’API dans le fichier de spécification Swagger en remplaçant la ligne :
api = supertest('http://0.0.0.0:8080'); |
par :
api = supertest('http://XX.XX.XX.XX:8080'); |
XX.XX.XX.XX étant l’adresse IP de votre hôte.
Créer le fichier Dockerfile qui permet de générer une image Docker :
cat <<EOF> Dockerfile |
FROM node |
RUN npm update |
RUN npm install chai |
RUN npm install supertest |
RUN npm install -g mocha |
COPY entrypoint.sh / |
WORKDIR /app |
ENTRYPOINT ["/entrypoint.sh"] |
EOF |
Ajouter un shell de point d’entrée :
cat <<EOF> entrypoint.sh |
#!/bin/bash |
mocha test.js --reporter spec |
cp report.xml /report |
cp report.html /report |
EOF |
Générer l’image Docker :
docker build -t supertest-api . |
Pour utiliser l’image Docker, il suffit de procéder ainsi :
docker run --rm -v $PWD/app:/app -v $PWD/report:/report supertest-api |
Nous avons maintenant abordé plusieurs approches de test des spécifications Swagger et de leur implémentation.