swagger-express-jsdoc

Example of Express with swagger-jsdoc

Install

git

1$ git clone https://github.com/SangHakLee/swagger-express-jsdoc.git

NPM

1$ npm i swagger-express-jsdoc
2$ cd node_modules

How to use

Start Server

1$ cd swagger-express-jsdoc
2$ npm install
3$ npm start

Use swagger-jsdoc

http://localhost:3000/api-docs/

How to add api-docs

This application is based on Swagger, swagger-jsdoc and swagger-ui-express

app.js

1// ...
2var swaggerUi = require('swagger-ui-express'); // line 7
3var swaggerJSDoc = require('swagger-jsdoc'); // line 8
4
5// ...
6var options = { // line 27
7  swaggerDefinition: {
8    info: {
9      title: 'swagger-express-jsdoc', // Title (required)
10      version: '1.0.0', // Version (required)
11    },
12  },
13  apis: ['./routes/*'], // Path to the API docs
14};
15var swaggerSpec = swaggerJSDoc(options); // line 36
16
17// ...
18app.get('/api-docs.json', function(req, res) { // line 41
19  res.setHeader('Content-Type', 'application/json');
20  res.send(swaggerSpec);
21});
22
23// ...
24app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec)); // line 45

var options (line 27)

Your Swagger docs information here. swagger-jsdoc

swaggerDefinition.info

specification

1{
2  "title": "Swagger Sample App",
3  "description": "This is a sample server Petstore server.",
4  "termsOfService": "http://swagger.io/terms/",
5  "contact": {
6    "name": "API Support",
7    "url": "http://www.swagger.io/support",
8    "email": "support@swagger.io"
9  },
10  "license": {
11    "name": "Apache 2.0",
12    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
13  },
14  "version": "1.0.1"
15}

apis

Your routing files path. If your routing file path like this,

• /controllers/users.js
• /controllers/stores.js

Set your apis value like this, apis: ['./controllers/*']

var swaggerSpec (line 36)

It will be json object. Your option value and apis value are combined.

/api-docs.json (line 41)

This returns a simple json document. http://localhost:3000/api-docs.json

/api-docs (line 45)

This will convert the json document to Swagger-ui. So when you connect with http://localhost:3000/api-docs, it will make you see beautiful documents.