Create Document from swagger-node-express spec.js and model.js

Question

resources.js

'use strict';
var sw = require('swagger-node-express');
var paramTypes = sw.paramTypes;
var swe = sw.errors;

var petData = require('./service.js');

// the description will be picked up in the resource listing
exports.findById = {
  'spec': {
    description : 'Operations about pets',  
    path : '/pet/{petId}',
    method: 'GET',
    summary : 'Find pet by ID',
    notes : 'Returns a pet based on ID',
    type : 'Pet',
    nickname : 'getPetById',
    produces : ['application/json'],
    parameters : [paramTypes.path('petId', 'ID of pet that needs to be fetched', 'string')],
    responseMessages : [swe.invalid('id'), swe.notFound('pet')]
  },
  'action': function (req,res) {
      console.log('findById call');
    if (!req.params.petId) {
      throw swe.invalid('id'); }
    var id = parseInt(req.params.petId);
    var pet = petData.getPetById(id);

    if(pet) { 
        res.send(JSON.stringify(pet));
    } else { 
        throw swe.notFound('pet', res); 
    }
  }
};

model.js

exports.models = {
    'Pet':{
      'id':'Pet',
      'required': ['id', 'name'],
      'properties':{
        'id':{
          'type':'integer',
          'format':'int64',
          'description': 'Unique identifier for the Pet',
          'minimum': '0.0',
          'maximum': '100.0'
        },
        'name':{
          'type':'string',
          'description': 'Friendly name of the pet'
        }
      }
    }
  };

Hi I am using swagger-node-express in my node.js application. I successfully configured and it is working fine.

But right now I am facing Problem in documenting with swagger-ui. swagger-ui need JSON file. How to generate document from this two file.

Answer 1

Swagger-node-express generates the json from the spec that you provided. You just need to tell it where to publish it by calling

swagger.configureSwaggerPaths('', 'api-docs', '');

That publishes the json api description at [yourdomain]/api-docs, such as

localhost:8080/api-docs

Ofcourse you can change 'api-docs' to any name you want.

To inspect your api using swagger-ui you need to have that unpacked somewhere in a directory. Mine is in ../swagger-ui/dist. Tell express to serve the files in there in a static way, and give it a route, like /docs:

var dirname = __dirname + '/../swagger-ui/dist/';
var docs_handler = express.static(dirname);
app.get(/^\/docs(\/.*)?$/, function(req, res, next) {
  if (req.url === '/docs') { // express static barfs on root url w/o trailing slash
    res.writeHead(302, { 'Location' : req.url + '/' });
    res.end();
    return;
  }
  // take off leading /docs so that connect locates file correctly
  req.url = req.url.substr('/docs'.length);
  return docs_handler(req, res, next);
});

Now pointing your browser at

localhost:8080/docs

should show the swagger-ui interface. To make the UI directly display your api specs, add your api-docs url in the swagger-ui index.html file:

window.swaggerUi = new SwaggerUi({
    url: "/api-docs",

There should be a neater way to do that last tweak, but I haven't discovered that yet.