CODEWITHSUNDEEP
node.jsapiazureserverswagger
Ernani
Ernani

Reputation: 1049

Generate Swagger Document for existing NodeJS server

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.

Upvotes: 31

Views: 49692

Answers (5)

Miguel Gamboa
Miguel Gamboa

Reputation: 9343

Most alternatives require some sort of API specification through Json, Yaml or even embedded in JSdocs. On the other hand there are some runtime analyzers intercepting HTTP requests and building that specification on-demand.

express-sitemap-html follows a different approach inspecting the express object and its routes at setup time. Thus it always provides an up-to-date swagger UI for installed routes on existing express instance.

const sitemap = require('express-sitemap-html')
...
sitemap.swagger('Title', app) // app is an express instance

Then get swagger UI from your domain /api-docs.

Upvotes: 2

centree
centree

Reputation: 2439

A lot of developers are still having this problem so I built an open-source tool to help -- the tool is kind of like Git for APIs. It works by running a proxy while you're developing the API, analyzing the traffic, and updating the spec for you as the API's behavior changes. Hopefully, the workflow saves you a lot of time: https://github.com/opticdev/optic

Upvotes: 2

mpashkovskiy
mpashkovskiy

Reputation: 298

Question is a bit old but still. It is possible to generate completely automatically Swagger (OpenAPI) specification just by embedding analysis middleware like this: https://github.com/mpashkovskiy/express-oas-generator

const express = require('express');    
const expressOasGenerator = require('express-oas-generator');
let app = express();
expressOasGenerator.init(app, {});

run some client or REST API tests agains your service and open http://host:port/api-docs

Upvotes: 21

Ahmad Abdelghany
Ahmad Abdelghany

Reputation: 13198

To my knowledge, your options are:

  1. Using swagger-node-express which is very cumbersome in my opinion.
  2. Writing up the swagger document manually yourself with the help of swagger editor as suggested in this SO Answer

If you go for option 2, you could use swagger-ui-express to generate the swagger-ui

Upvotes: 2

Gary Liu
Gary Liu

Reputation: 13918

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.

Upvotes: 13

Related Questions