Generate Swagger Document for existing NodeJS server
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
It’s not difficult to integrate Swagger in exist express applications following this tutorial.
Generally, we can follow these steps:
Add the dependencies in our
package.json
, and runnpm install
to install them. The dependencies should be:"dependencies": { "swagger-node-express": "~2.0", "minimist": "*", "body-parser": "1.9.x", ...}
Download the zip project of Swagger-UI, copy the
dist
folder into the root directory of our project, the directory should almost like:
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' );
Set up a subpath for swagger doc:
var subpath = express();app.use(bodyParser());app.use("/v1", subpath);swagger.setAppHandler(subpath);
Make sure that
/dist
is able to serve static files in express:app.use(express.static('dist'));
Set the info for API:
swagger.setApiInfo({ title: "example API", description: "API to do something, manage something...", termsOfServiceUrl: "", contact: "yourname@something.com", license: "", licenseUrl: ""});
Introduce
/dist/index.html
for swagger UI:subpath.get('/', function (req, res) { res.sendfile(__dirname + '/dist/index.html');});
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');
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";}
Create
api-docs.json
file with the info of your APIs, put it in thedist
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.
To my knowledge, your options are:
- Using swagger-node-express which is very cumbersome in my opinion.
- 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