Making a Swagger Document Using Swagger-UI
By: Rashmi Shehana
Tags: Swagger Ui, Swagger, Documenting, Nodejs, Node

— With Node.js —

image 1.0

In this tutorial, we are going to discuss how to make a swagger document with Swagger UI Express in Node.js for an existing project. Image 1.0 shows a real swagger document that I created for an API during internship at Sysco LABS. When you expand the collapsed rows, you can run each endpoint as in the bellow image clicking ‘Try it Out’ button.

image 2.0

You can fill the necessary parameters and execute the endpoint. Now let’s see how we can implement this swagger document.

First, you should install the swagger UI express npm module using this command.

npm i swagger-ui-express

Next, we need to make the route for the swagger document. ‘swagger.json’ is the file in which I am going to write my swagger documentation. And you should have installed express for routing purpose.

const express = require('express');

const app = express();

const swaggerUi = require(‘swagger-ui-express’);

const swaggerDocument = require(‘./swagger.json’); app.use('/doc',swaggerUi.serve, swaggerUi.setup(swaggerDocument));

We have created the routing for our swagger document. Now let’s see how we can write the content in swagger. Swagger definitions can be written in JSON or YAML. But in this tutorial, we are going to write the definition in JSON.

In a swagger document, there are several important attributes we should fill out. In this code, you can see those attributes. But still, you can skip some of them if you don’t need those descriptions to be in the document.

{

“swagger”: “2.0”,

“info”: {

“version”: “1.0.0 and 2.0.0”,

“title”: “LDP-API”,

“description”: “This is all about my LSP-API”

},

“host”: “localhost:8081”,

“basePath”: “/ldp-api/”,

“securityDefinitions”:{

“basicAuth”:{

“type”: “basic”

}

},

“security”:{

“basicAuth”: []

},

“tags”: [

{

“name”: “CouchClusterAllocator API”,

“description”: “API for Allocate Couch Clusters for merchants . Requests should have a basic auth header.”

},

{

“name” : “FileStore API”,

“description” : “API for manipulate receipts . Requests should have a basic auth header.Content type must be application/json.”

}

],

“consumes”: [

“application/json”

],

“produces”: [

“application/json”

],

“paths”: {}

}

In here “swagger”: “2.0”, is the swagger version. Under info, you have to set some details such as version, title, and description of the system. You can skip any or all of them as well.

I have added basic auth as the security definition here. There are several other security definitions that you can add and you can find it here.

“tags” are the main heading in the swagger document. (Refer image 1.0 to identify what are the “tags” related to the above JSON code.) ”consumes” and the ”produces” are the type of input and output which accepts by the swagger document.

Next, we have to describe “paths” or the endpoints which we need to add.

"paths": {

"/CouchClusterAllocator/1.0.0/cluster": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Allocating a couch cluster for a merchant",

"responses": {

"200": {

"description": "{

cluster: \"clusterId\",

couchDBUri: \"couchDB Uri\"

}"

}

}

}

},

"/CouchClusterAllocator/1.0.0/clusterUri/{dbName}": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Get Cluster URI by Db name",

"parameters": [

{

"name": "dbName",

"in": "path",

"required": true,

"description": "Name of Database that we want to find uri",

"type": "string"

}

],

"responses": {

"200": {

"description": "{

dbName: 'DB name',

couchDBUri: 'Couch DB Uri'

}"

}

}

}

},

"/CouchClusterAllocator/1.0.0/allocateCluster": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Allocate Cluster For Merchants",

"parameters": [

{

"name": "merchantId",

"in": "query",

"required": false,

"description": "ID of Merchant",

"type": "string"

}

],

"responses": {

"200": {

"description": "{

dbName: 'DB Name',

couchDBUri: 'Couch Db Uri'

}"

}

}

}

},

"/CouchClusterAllocator/1.0.0/getCouchDbUriByDbName": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Get Couch Db Uri by DB name",

"parameters": [

{

"name": "dbName",

"in": "query",

"required": false,

"description": "Name of Database that we want to find uri",

"type": "string"

}

],

"responses": {

"200": {

"description": "{

dbName: 'DB Name',

couchDBUri: 'couch DB Uri'

}"

}

}

}

},

"/fsapi/{version}": {

"post": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "File",

"in": "body",

"description": "File Details",

"schema": {

"$ref": "#/definitions/File_v2_post"

}

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

}

],

"summary": "Store a receipt",

"responses": {

"201": {

"description": "{

'id': 'ID of the stored receipt'

}"

}

}

}

},

"/fsapi/{version}/{id}": {

"put": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "File",

"in": "body",

"description": "File Details",

"schema": {

"$ref": "#/definitions/File"

}

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

},

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

}

],

"summary": "Update a receipt",

"responses": {

"200": {

"description": "{

'id': 'ID of the stored receipt'

}"

}

}

},

"delete": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

},

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

}

],

"summary": "Delete a receipt",

"responses": {

"200": {

"description": "Successfully deleted the receipt!!"

}

}

},

"get": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

}

],

"summary": "Get a receipt by ID",

"responses": {

"200": {

"description": "This should return the receipt."

}

}

}

},

"/fsapi/{version}/{id}/json": {

"get": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

}

],

"summary": "Get a receipt in json format",

"responses": {

"200": {

"description": "{

'fileName' : 'Name of the attachment e.g logo.png'

'fileMimeType': 'Type of the attachement e.g image/jpeg'

'attachment': 'Content of the attachment encoded in Base64,

}"

}

}

}

}

}{

"/CouchClusterAllocator/1.0.0/cluster": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Allocating a couch cluster for a merchant",

"responses": {

"200": {

"description": "{ cluster: "clusterId", couchDBUri: "couchDB Uri" }"

}

}

}

},

"/CouchClusterAllocator/1.0.0/clusterUri/{dbName}": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Get Cluster URI by Db name",

"parameters": [

{

"name": "dbName",

"in": "path",

"required": true,

"description": "Name of Database that we want to find uri",

"type": "string"

}

],

"responses": {

"200": {

"description": "{ dbName: 'DB name', couchDBUri: 'Couch DB Uri' }"

}

}

}

},

"/CouchClusterAllocator/1.0.0/allocateCluster": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Allocate Cluster For Merchants",

"parameters": [

{

"name": "merchantId",

"in": "query",

"required": false,

"description": "ID of Merchant",

"type": "string"

}

],

"responses": {

"200": {

"description": "{ dbName: 'DB Name', couchDBUri: 'Couch Db Uri' }"

}

}

}

},

"/CouchClusterAllocator/1.0.0/getCouchDbUriByDbName": {

"get": {

"tags": [

"CouchClusterAllocator API"

],

"summary": "Get Couch Db Uri by DB name",

"parameters": [

{

"name": "dbName",

"in": "query",

"required": false,

"description": "Name of Database that we want to find uri",

"type": "string"

}

],

"responses": {

"200": {

"description": "{ dbName: 'DB Name', couchDBUri: 'couch DB Uri' }"

}

}

}

},

"/fsapi/{version}": {

"post": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "File",

"in": "body",

"description": "File Details",

"schema": {

"$ref": "#/definitions/File_v2_post"

}

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

}

],

"summary": "Store a receipt",

"responses": {

"201": {

"description": "{ 'id': 'ID of the stored receipt' }"

}

}

}

},

"/fsapi/{version}/{id}": {

"put": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "File",

"in": "body",

"description": "File Details",

"schema": {

"$ref": "#/definitions/File"

}

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

},

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

}

],

"summary": "Update a receipt",

"responses": {

"200": {

"description": "{ 'id': 'ID of the stored receipt' }"

}

}

},

"delete": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

},

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

}

],

"summary": "Delete a receipt",

"responses": {

"200": {

"description": "Successfully deleted the receipt!!"

}

}

},

"get": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

}

],

"summary": "Get a receipt by ID",

"responses": {

"200": {

"description": "This should return the receipt."

}

}

}

},

"/fsapi/{version}/{id}/json": {

"get": {

"tags": [

"FileStore API"

],

"parameters": [

{

"name": "id",

"in": "path",

"description": "ID of the receipt"

},

{

"name": "version",

"in": "path",

"description": "version of the api (1.0.0 or 2.0.0)"

}

],

"summary": "Get a receipt in json format",

"responses": {

"200": {

"description": "{ 'fileName' : 'Name of the attachment e.g logo.png' 'fileMimeType': 'Type of the attachement e.g image/jpeg' 'attachment': 'Content of the attachment encoded in Base64, }"

}

}

}

}

}

This is the “path” object of the swagger document which creates image 1.0. For each endpoint, you have to add the related “tag” and the Http method as above.

If the endpoint needs to have any parameters, then you can add them by adding their names and descriptions. You should indicate where the parameter should be attached by providing the value of “in” as “body” or “path”.

If you need to provide a particular template or format for a JSON object which should set in the request body, It should be added in definitions section at the end. It can be used like the bold text in the above code. I have given a simple example for a “definition” for object {resultCode: number, id: number} .

"definitions": {

" File_v2_post ": {

"type": "object",

"properties": { "resultCode": {

"type": "number"

},

"id" : {

"type" : "number"

}



}

}

}

So that’s how we can make a swagger document easily with swagger-UI. You can comment below if you have any questions.

Happy Coding !!!!