Swagger, API, Node – Documenter une API avec Swagger

by Posted on

Swagger, c’est un assortiment d’outils indispensables pour documenter une API. L’aspect le plus saisissant de cet outil est sa faculté à générer une documentation digne de ce nom , une documentation qui peut-être maintenu et pas seulement par les développeurs.

1. Une fois dans la console, l’installation se fait avec la commande suivante. On fait une installation globale.

npm install -g swagger

2. Se mettre dans le répertoire où on veut créer son app
cd /votre_chemin_vers/doc_api_swagger_io/

3. Créer votre projet avec swagger. On choisit un nom pour l’api api_2_movies et on seletionne ensuite express

swagger project create

Swagger, API, - Documenter une API avec Swagger

Un fichier nommé swagger.yaml va se créer automatiquement. C’est ce fichier par exemple que vous allez pouvoir éditer afin de la modifier au fur et à mesure que vous concevez votre API avec node.

Le résultat est visible à cette adresse http://127.0.0.1:10010/hello?name=Scott

swagger project start

Le résultat est visible à cette adresse http://127.0.0.1:50226/#/

swagger project edit

Swagger, API, - Documenter une API avec Swagger

D’autres commandes pouvant être utile :

Vérifier si votre fichier swagger.yaml est valide.

swagger project verify

Swagger, API, - Documenter une API avec Swagger

Pour sauvegarder la documentation

npm install swagger-tools --save
swagger project start

Il est que vous deviez installer toutes les dépendances.

npm install
npm install swagger-tools --save
swagger project start

Pour générer la documentation http://localhost:10010/docs, il suffit d’ajouter les lignes marquées par le commentaire /* For docs */ dans le fichier app.js
Swagger, API, - Documenter une API avec Swagger

	'use strict';
 
	var SwaggerExpress = require('swagger-express-mw');
	/* For docs */
	var SwaggerUi = require('swagger-tools/middleware/swagger-ui');
	var app = require('express')();
	module.exports = app; // for testing
 
	var config = {
	  appRoot: __dirname // required config
	};
 
	SwaggerExpress.create(config, function(err, swaggerExpress) {
	  if (err) { throw err; }
 
	  /* For docs */
	  app.use(SwaggerUi(swaggerExpress.runner.swagger));
 
	  // install middleware
	  swaggerExpress.register(app);
 
	  var port = process.env.PORT || 10010;
	  app.listen(port);
 
	  if (swaggerExpress.runner.swagger.paths['/hello']) {
	    console.log('try this:\ncurl http://127.0.0.1:' + port + '/hello?name=Scott');
	  }
	});

Source : http://robferguson.org/2015/06/06/build-your-microservices-api-with-swagger/

Un autre exemple d’API

Voilà un exemple beaucoup plus abouti qui mixe swagger, une API qui se créer au fil de l’eau avec express, mongoose et lodash et une utilisation de Postman pour manipuler cette API nouvellement créée.
Source : https://www.youtube.com/watch?v=i9yOksgUQ9Y

En savoir plus

Published by Bruno Flaven

Bruno Flaven has been a Project Manager in a wide variety of Internet business applications both in Mobile and in Desktop for 20 years now. You can find more information about his professional life on his personal website (www.flaven.fr) or his linkedin profile: https://fr.linkedin.com/in/brunoflaven. He is currently working In France Media Monde (FMM) mostly on mobile applications (iOS and Android). He is currently P.O for a Backoffice project made with Symfony. He also made few trainings to facilitate the handling of the tools that he helps to make.

Related Posts