Generate Swagger Document for existing NodeJS server

Ernani picture Ernani · Nov 5, 2015 · Viewed 29.8k times · Source

According to Swagger website, there are two approaches: Bottom-up and Top-down.

I have an existing NodeJS server that I'd like to deploy in the Azure enviroment, that require a swagger document (API APP).

Does anyone know a tool for generating the swagger using the code? Even better if you could point a tutorial. I couldn't find it.

Answer

Gary Liu - MSFT picture Gary Liu - MSFT · Nov 6, 2015

It’s not difficult to integrate Swagger in exist express applications following this tutorial.

Generally, we can follow these steps:

  1. Add the dependencies in our package.json, and run npm install to install them. The dependencies should be:

    "dependencies": {
            "swagger-node-express": "~2.0",
            "minimist": "*",
            "body-parser": "1.9.x",
            ...
    }
    
  2. Download the zip project of Swagger-UI, copy the dist folder into the root directory of our project, the directory should almost like:

enter image description here

  1. Introduce the dependencies at the beginnng of app.js:

    var argv = require('minimist')(process.argv.slice(2));
    var swagger = require("swagger-node-express");
    var bodyParser = require( 'body-parser' );
    
  2. Set up a subpath for swagger doc:

    var subpath = express();
    app.use(bodyParser());
    app.use("/v1", subpath);
    swagger.setAppHandler(subpath);
    
  3. Make sure that /dist is able to serve static files in express: app.use(express.static('dist'));

  4. Set the info for API:

    swagger.setApiInfo({
        title: "example API",
        description: "API to do something, manage something...",
        termsOfServiceUrl: "",
        contact: "[email protected]",
        license: "",
        licenseUrl: ""
    });
    
  5. Introduce /dist/index.html for swagger UI:

    subpath.get('/', function (req, res) {
        res.sendfile(__dirname + '/dist/index.html');
    });
    
  6. Complete the swagger configurations:

    swagger.configureSwaggerPaths('', 'api-docs', '');
    
    var domain = 'localhost';
    if(argv.domain !== undefined)
        domain = argv.domain;
    else
        console.log('No --domain=xxx specified, taking default hostname "localhost".');
    var applicationUrl = 'http://' + domain;
    swagger.configure(applicationUrl, '1.0.0');
    
  7. Configure doc file dependence in /dist/index.html:

    if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
    } else {
        <del>url = "http://petstore.swagger.io/v2/swagger.json";</del>
        url = "/api-docs.json";
    }
    
  8. Create api-docs.json file with the info of your APIs, put it in the dist folder.

Run the Express app on local, visit http://localhost:3000/v1, we can check the swagger doc.

Here is my test sample repo for your reference.