Merge pull request #18 from renanlopescoder/swagger-api-doc

Feature(docs): add swagger documentation

Author: renanlopescoder

package.json

@@ -1,6 +1,6 @@
 {
   "name": "node_api",
-  "version": "3.1.5",
+  "version": "3.2.0",
   "description": "Node API is production ready and open source project in Node, Express, MongoDB",
   "scripts": {
     "start": "node server.js"
@@ -13,9 +13,11 @@
     "consign": "^0.1.6",
     "cors": "^2.8.3",
     "express": "^4.14.0",
-    "jsonwebtoken": "^7.2.1",
-    "mongoose": "5.9.10",
-    "nodemailer": "6.4.6"
+    "jsonwebtoken": "^8.5.1",
+    "mongoose": "5.9.11",
+    "nodemailer": "6.4.6",
+    "swagger-jsdoc": "^4.0.0",
+    "swagger-ui-express": "^4.1.4"
   },
   "engines": {
     "node": "14.0.0"

src/app/Controllers/AuthController.js

@@ -14,7 +14,7 @@ class AuthController {
       if (!match) {
         res.status(401).send({ error: "error", message: "Password mismatch" });
         token = jwt.sign({ user_id: user._id }, secret, {
-          expiresIn: "3h"
+          expiresIn: "3h",
         });
       }
 
@@ -24,7 +24,7 @@ class AuthController {
         username: user.username,
         photo: user.photo,
         email: user.email,
-        token: token
+        token: token,
       });
     } catch (error) {
       res

src/app/Models/Project.js

@@ -1,38 +1,38 @@
-var mongoose = require('mongoose');
+const mongoose = require("mongoose");
 
-var schema = mongoose.Schema({
-	project: {
-		type: String,
-		required: false
-	},
-	technologies: {
-		type: String,
-		required: false
-	},
-	description: {
-		type: String,
-		required: false
-	},
-	demoLink: {
-		type: String,
-		required: false
-	},
-	githubLink: {
-		type: String,
-		required: false
-	},
-	author: {
-		type: String,
-		required: false
-	},
-	authorLink: {
-		type: String,
-		required: false
-	},
-	status: {
-		type: String,
-		required: false
-	} 
+const schema = mongoose.Schema({
+  project: {
+    type: String,
+    required: false,
+  },
+  technologies: {
+    type: String,
+    required: false,
+  },
+  description: {
+    type: String,
+    required: false,
+  },
+  demoLink: {
+    type: String,
+    required: false,
+  },
+  githubLink: {
+    type: String,
+    required: false,
+  },
+  author: {
+    type: String,
+    required: false,
+  },
+  authorLink: {
+    type: String,
+    required: false,
+  },
+  status: {
+    type: String,
+    required: false,
+  },
 });
 
-mongoose.model('Project', schema);
+mongoose.model("Project", schema);

src/app/Models/User.js

@@ -1,26 +1,58 @@
-var mongoose = require('mongoose');
+/**
+ * @swagger
+ *  components:
+ *    schemas:
+ *      User:
+ *        type: object
+ *        required:
+ *          - username
+ *          - email
+ *          - password
+ *        properties:
+ *          username:
+ *            type: string
+ *          email:
+ *            type: string
+ *            format: email
+ *            description: Email for the user, needs to be unique.
+ *          password:
+ *            type: string
+ *          photo:
+ *            type: string
+ *            description: Image URL string
+ *          nickname:
+ *            type: string
+ *        example:
+ *           username: Renan
+ *           email: fake@email.com
+ *           password: 123456aa
+ *           nickname: Dexter
+ *           photo: https://photourl.com/image.png
+ */
 
-var schema = mongoose.Schema({
-	username: {
-		type: String,
-		required: true
-	},
-	password : {
-		type: String,
-		required: true
-	},
-  email : {
-		type: String,
-		required: true
-	},
-	photo : {
-		type: String,
-		required: false
-	},
-	nickname: {
-		type: String,
-		required: false
-	}
+const mongoose = require("mongoose");
+
+const schema = mongoose.Schema({
+  username: {
+    type: String,
+    required: true,
+  },
+  password: {
+    type: String,
+    required: true,
+  },
+  email: {
+    type: String,
+    required: true,
+  },
+  photo: {
+    type: String,
+    required: false,
+  },
+  nickname: {
+    type: String,
+    required: false,
+  },
 });
 
-mongoose.model('User', schema);
+mongoose.model("User", schema);

src/config/express.js

@@ -2,12 +2,21 @@ const express = require("express");
 const bodyParser = require("body-parser");
 const cors = require("cors");
 const consign = require("consign");
+const swaggerUi = require("swagger-ui-express");
+const swaggerJsdoc = require("swagger-jsdoc");
+
+const swaggerOptions = require("../../swagger");
+
 const app = express();
 
 app.use(cors({ origin: "*" }));
 app.use(bodyParser.json());
 app.set("secret", "opensecret");
 
+const specs = swaggerJsdoc(swaggerOptions);
+app.use("/docs", swaggerUi.serve);
+app.get("/docs", swaggerUi.setup(specs, { explorer: true }));
+
 consign({ cwd: process.cwd() + "/src" })
   .include("app/Models")
   .then("app/Controllers")

src/routes/project.js

@@ -1,6 +1,5 @@
-module.exports = src => {
+module.exports = (src) => {
   const { ProjectController } = src.app.Controllers;
-
   src.get("/projects", ProjectController.getAllProjects);
   src.post("/projects/create", ProjectController.createProject);
   src.put("/projects/update/:id", ProjectController.updateProject);

src/routes/user.js

@@ -1,4 +1,33 @@
-module.exports = src => {
+/**
+ * @swagger
+ * tags:
+ *   name: Users
+ *   description: User management
+ */
+
+/**
+ * @swagger
+ * path:
+ *  /users/create:
+ *    post:
+ *      summary: Create a new user
+ *      tags: [Users]
+ *      requestBody:
+ *        required: true
+ *        content:
+ *          application/json:
+ *            schema:
+ *              $ref: '#/components/schemas/User'
+ *      responses:
+ *        "200":
+ *          description: A user schema
+ *          content:
+ *            application/json:
+ *              schema:
+ *                $ref: '#/components/schemas/User'
+ */
+
+module.exports = (src) => {
   const { UserController } = src.app.Controllers;
 
   src.get("/users", UserController.getAllUsers);

swagger.json

@@ -0,0 +1,28 @@
+{
+  "swaggerDefinition": {
+    "openapi": "3.0.0",
+    "info": {
+      "title": "Node Rest API",
+      "version": "1.0.0",
+      "description": "Node API is production ready and open source project in Node, Express, MongoDB",
+      "license": {
+        "name": "MIT",
+        "url": "https://choosealicense.com/licenses/mit/"
+      },
+      "contact": {
+        "name": "Renan Lopes",
+        "url": "https://renanlopes.com",
+        "email": "renanlopescoder@gmail.com"
+      }
+    },
+    "servers": [
+      {
+        "url": "http://localhost:8080"
+      },
+      {
+        "url": "https://rest-api-node.herokuapp.com"
+      }
+    ]
+  },
+  "apis": ["./src/app/Models/User.js", "./src/routes/user.js"]
+}