Adding swagger to my nodejs restify project

Question

I am having a base nodejs restify server with two simple methods one GET and one POST. I am trying to add swagger API documentation on top of my restify services. Found support for express.

Also found some libaries https://www.npmjs.com/package/swagger-restify . But dont know how to use this in the code.How to add this in a way all my api documentation will come in 'http://localhost:5000/docs' or something like that.

My base restify code is as below.

var restify=require('restify');
var restifyPlugins = require('restify-plugins');
var cors = require('cors');
var server=restify.createServer({name:'test'});

server.use(restifyPlugins.acceptParser(server.acceptable));
server.use(restifyPlugins.queryParser());
server.use(restifyPlugins.fullResponse());
server.use(restifyPlugins.bodyParser({
    maxBodySize: 0,

    multiples: true
}));

server.use(cors({
    origin: '*',
    methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',
    credentials:'false',
    optionsSuccessStatus: 200 /* some legacy browsers (IE11, various SmartTVs) choke on 204 */ ,
}))

server.use(restifyPlugins.authorizationParser());


server.get({path:'/test'},function(req,res,next){
    
    console.log("TEST API")
    res.send("hello");
    });

server.post({path:'/postCheck'},function(req,res,next){

    console.log("TEST post API",req.body.userId)
    res.send("hello post");
    });



server.listen(5000,function(){
    console.log("Starting server at :%s,%s",server.url,server.name)
})

Answer 1

According to the swagger-restify documentation, when initializing the swagger, it is required to pass the apis property as an array with the API definition file names with their relative paths. API definition can be done either by using jsdoc comments or creating a yml file A clear idea of API definition creation can be obtained by referring to the swagger-restify documentation since it contains examples for both approaches.

Further, you need to add swagger UI-related HTML components to a folder that serves static content and need to include the path in the swagger config as swaggerUI property.

For the following code segment, I assumed those are in the ./public folder.

Configure the server like this,

var restify=require('restify');
var restifyPlugins = require('restify-plugins');
var swagger = require('swagger-restify');
var cors = require('cors');
var server=restify.createServer({name:'test'});

server.use(restifyPlugins.acceptParser(server.acceptable));
server.use(restifyPlugins.queryParser());
server.use(restifyPlugins.fullResponse());
server.use(restifyPlugins.bodyParser({
    maxBodySize: 0,

    multiples: true
}));


  swagger.init(server, {
    apiVersion: '1.0',
    swaggerVersion: '1.0',
    swaggerURL: '/docs',
    swaggerUI: './public',
    basePath: 'http://localhost:5000',
    info: {
      title: 'swagger-restify sample app',
      description: 'Swagger + Restify = {swagger-restify}'
    },
    apis: ['./api.js', './api.yml'],
    middleware: function(req, res){}
  });


server.use(cors({
    origin: '*',
    methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',
    credentials:'false',
    optionsSuccessStatus: 200 /* some legacy browsers (IE11, various SmartTVs) choke on 204 */ ,
}))

server.use(restifyPlugins.authorizationParser());


server.get({path:'/test'},function(req,res,next){
    
    console.log("TEST API")
    res.send("hello");
    });

server.post({path:'/postCheck'},function(req,res,next){

    console.log("TEST post API",req.body.userId)
    res.send("hello post");
    });  



server.listen(5000,function(){
    console.log("Starting server at :%s,%s",server.url,server.name)
});

Answer 2

Before you start your server, just set up a swagger resource as swagger-restify document:

// import swagger lib
var swagger = require('swagger-restify');

...
swagger.init(server, { // set up swagger for "server"
    apiVersion: '1.0',
    swaggerVersion: '1.0',
    swaggerURL: '/docs', // endpoint what you want to access
    swaggerJSON: '/api-docs.json',
    swaggerUI: './public',
    basePath: 'http://localhost:5000',
    info: {
      title: 'swagger-restify sample app',
      description: 'Swagger + Restify = {swagger-restify}'
    },
    apis: ['./api.js', './api.yml'],
    middleware: function(req, res){}
});

server.listen(5000,function(){
    console.log("Starting server at :%s,%s",server.url,server.name)
})

Answer 3

So I did manage to add Swagger Documentation to my Node.js and Restify api. And I hope that someone finds this helpfull and that nothing got deprecated.

So the package i am using is called restify-swagger-jsdoc And it very easy to configure you will need to

https://www.npmjs.com/package/restify-swagger-jsdoc

npm i restify-swagger-jsdoc

and then in your file where you initialize the const server = restify.createServer() add the following code snippet

const restifySwaggerJsdoc = require('restify-swagger-jsdoc');

restifySwaggerJsdoc.createSwaggerPage({
  title: 'API documentation',
  version: '1.0.0',,
  server: server, // created restify server object,
  path: '/api-docs', // url to view generated docs,
  apis: ['./src/routes/*.js'], // this is where swagger can find 
                               // files containing jsdoc or can point 
                               // to api.yaml file
                               // to generate docs from. 
});

And once you run your server and you jsdoc swagger annotations and comment are added to your routes you should be able to view the generate Swagger docs at the path mentioned above.