{"id":10677,"date":"2016-04-12T17:00:47","date_gmt":"2016-04-12T15:00:47","guid":{"rendered":"http:\/\/flaven.fr\/?p=10677"},"modified":"2016-04-12T17:01:51","modified_gmt":"2016-04-12T15:01:51","slug":"swagger-api-node-documenter-une-api-avec-swagger","status":"publish","type":"post","link":"https:\/\/flaven.fr\/2016\/04\/swagger-api-node-documenter-une-api-avec-swagger\/","title":{"rendered":"Swagger, API, Node – Documenter une API avec Swagger"},"content":{"rendered":"\n

Swagger, c’est un assortiment d’outils indispensables pour documenter une API. L’aspect le plus saisissant de cet outil est sa facult\u00e9 \u00e0 g\u00e9n\u00e9rer une documentation digne de ce nom , une documentation qui peut-\u00eatre maintenu et pas seulement par les d\u00e9veloppeurs. <\/p>\n

1. Une fois dans la console, l’installation se fait avec la commande suivante. On fait une installation globale.<\/p>\n

npm install -g swagger<\/pre>\n
2. Se mettre dans le r\u00e9pertoire o\u00f9 on veut cr\u00e9er son app
\ncd \/votre_chemin_vers\/doc_api_swagger_io\/<\/p>\n
3. Cr\u00e9er votre projet avec swagger. On choisit un nom pour l’api api_2_movies<\/code> et on seletionne ensuite express<\/code><\/p>\n
swagger project create<\/pre>\n
\"Swagger,<\/p>\n
Un fichier nomm\u00e9 swagger.yaml<\/code> va se cr\u00e9er automatiquement. C’est ce fichier par exemple que vous allez pouvoir \u00e9diter afin de la modifier au fur et \u00e0 mesure que vous concevez votre API avec node.<\/p>\n
Le r\u00e9sultat est visible \u00e0 cette adresse http:\/\/127.0.0.1:10010\/hello?name=Scott<\/b><\/p>\n
swagger project start<\/pre>\n
Le r\u00e9sultat est visible \u00e0 cette adresse http:\/\/127.0.0.1:50226\/#\/<\/b><\/p>\n
swagger project edit<\/pre>\n
\"Swagger,<\/p>\n
D’autres commandes pouvant \u00eatre utile :<\/p>\n
V\u00e9rifier si votre fichier swagger.yaml<\/code> est valide.<\/b><\/p>\n
swagger project verify<\/pre>\n
\"Swagger,<\/p>\n
Pour sauvegarder la documentation  <\/p>\n
npm install swagger-tools --save<\/pre>\n
swagger project start<\/pre>\n
Il est que vous deviez installer toutes les d\u00e9pendances.<\/b><\/p>\n
npm install<\/pre>\n
npm install swagger-tools --save<\/pre>\n
swagger project start<\/pre>\n
Pour g\u00e9n\u00e9rer la documentation http:\/\/localhost:10010\/docs, il suffit d’ajouter les lignes marqu\u00e9es par le commentaire \/* For docs *\/<\/code> dans le fichier app.js<\/b>
\n\"Swagger,<\/p>\n
\r\n\t'use strict';\r\n\r\n\tvar SwaggerExpress = require('swagger-express-mw');\r\n\t\/* For docs *\/\r\n\tvar SwaggerUi = require('swagger-tools\/middleware\/swagger-ui');\r\n\tvar app = require('express')();\r\n\tmodule.exports = app; \/\/ for testing\r\n\r\n\tvar config = {\r\n\t  appRoot: __dirname \/\/ required config\r\n\t};\r\n\r\n\tSwaggerExpress.create(config, function(err, swaggerExpress) {\r\n\t  if (err) { throw err; }\r\n\r\n\t  \/* For docs *\/\r\n\t  app.use(SwaggerUi(swaggerExpress.runner.swagger));\r\n  \r\n\t  \/\/ install middleware\r\n\t  swaggerExpress.register(app);\r\n\r\n\t  var port = process.env.PORT || 10010;\r\n\t  app.listen(port);\r\n\r\n\t  if (swaggerExpress.runner.swagger.paths['\/hello']) {\r\n\t    console.log('try this:\\ncurl http:\/\/127.0.0.1:' + port + '\/hello?name=Scott');\r\n\t  }\r\n\t});\r\n\t\r\n<\/pre>\n
Source : http:\/\/robferguson.org\/2015\/06\/06\/build-your-microservices-api-with-swagger\/<\/a><\/p>\n
Un autre exemple d’API<\/h4>\n
Voil\u00e0 un exemple beaucoup plus abouti qui mixe swagger, une API qui se cr\u00e9er au fil de l’eau avec express, mongoose et lodash et une utilisation de Postman pour manipuler cette API nouvellement cr\u00e9\u00e9e.
\nSource : https:\/\/www.youtube.com\/watch?v=i9yOksgUQ9Y<\/a><\/p>\n
En savoir plus<\/h2>\n