docs: Add api documentation using swagger and JsDoc

.gitignore

@@ -21,4 +21,5 @@
 
 npm-debug.log*
 yarn-debug.log*
-yarn-error.log*
+yarn-error.log*
+pino-logger.log

README.md

@@ -83,19 +83,16 @@ Body:
 - `dev_api` : User's dev.to API token
 - `hash_api` : User's Hashnode API Token
 
-## Post From Hashnode to Dev or Medium
+## Swagger API documentation
 
-URI: [http://localhost:8080/api/v2/hash](http://localhost:8080/api/v2/hash)
+Access the api documentation using [http://localhost:8080/api-docs](http://localhost:8080/api-docs)
 
-Body:
+## Donating
+
+
+Help Us Pay off Our Domain and Hosting Charges<br>
 
-```json
-{
-    "url" : "https://blog.tomaszgil.me/make-the-most-out-of-your-next-migration-project",
-    "dev": true,
-    "medium": true,
-    "dev_api": "ShVKAZ1tb",
-    "medium_id": "1543cd6f0816d",
-    "medium_api":"2615790132f4a2d67f81e2696"
-}
-```
+
+<a href="https://www.buymeacoffee.com/integrateme">
+<img width="208" alt="snapshot-bmc-button" src="https://user-images.githubusercontent.com/72073401/140631132-f03daad8-c1e8-45ed-970b-94f204d5bba4.png">
+</a>

controller/postFromDev.controller.js

@@ -9,6 +9,37 @@ function devURLParser(URL) {
     return result;
 }
 
+/**
+ * @swagger
+ * components:
+ *  schemas:
+ *      DevPost:
+ *          type: object
+ *          properties:
+ *              url:
+ *                  type: string
+ *                  description: Article URL
+ *              medium:
+ *                  type: boolean
+ *                  description: If it should post to Medium
+ *              medium_userID:
+ *                  type: string
+ *                  description: User's medium's user ID can be fetched from (https://api.medium.com/v1/me)
+ *              medium_token:
+ *                  type: string
+ *                  description: User's medium's API token
+ *              hash:
+ *                  type: boolean
+ *                  description: If it should post to Hasnode
+ *              hash_token:
+ *                  type: string
+ *                  description: User's Hashnode API Token
+ *          example:
+ *              url: 383924
+ *              medium: false
+ *              hash: true
+ *              hash_token: fee010ff-bd64-496a-d28a58e30bb9
+ */
 exports.postFromDev = async (req, res, next) => {
     try {
         const { url, medium, hash } = req.body;

controller/postFromHash.controller.js

@@ -8,6 +8,39 @@ function hashURLParser(URL) {
   return arr[3];
 }
 
+/**
+ * @swagger
+ * components:
+ *  schemas:
+ *      HashPost:
+ *          type: object
+ *          properties:
+ *              url:
+ *                  type: string
+ *                  description: Article URL
+ *              dev:
+ *                  type: boolean
+ *                  description: If it should post to Dev.to
+ *              dev_api:
+ *                  type: string
+ *                  description: User's Dev.to API token
+ *              medium:
+ *                  type: boolean
+ *                  description: If it should post to Medium
+ *              medium_userID:
+ *                  type: string
+ *                  description: User's medium's user ID can be fetched from (https://api.medium.com/v1/me)
+ *              medium_token:
+ *                  type: string
+ *                  description: User's medium's API token
+ *          example:
+ *              url: 383924
+ *              dev: true
+ *              dev_api: ShVKKiC9AZ1tb
+ *              medium: true
+ *              medium_id: 1543cd6f0816d
+ *              medium_api: 2615790132f4a2d67f81e2696
+ */
 exports.postFromHash = async (req, res, next) => {
   const { url, medium, dev, dev_api, medium_id, medium_api } = req.body;
   const slug = hashURLParser(url)

controller/postFromMedium.controller.js

@@ -8,6 +8,35 @@ function mediumURLparser(URL) {
     return result;
 }
 
+/**
+ * @swagger
+ * components:
+ *  schemas:
+ *      MediumPost:
+ *          type: object
+ *          properties:
+ *              url:
+ *                  type: string
+ *                  description: Article URL
+ *              dev:
+ *                  type: boolean
+ *                  description: If it should post to Dev.to
+ *              dev_api:
+ *                  type: string
+ *                  description: User's Dev.to API token
+ *              hash:
+ *                  type: boolean
+ *                  description: If it should post to Hasnode
+ *              hash_token:
+ *                  type: string
+ *                  description: User's Hashnode API Token
+ *          example:
+ *              url: 383924
+ *              dev: true
+ *              dev_api: ShVKKiC9AZ1tb
+ *              hash: true
+ *              hash_token: fee010ff-bd64-496a-d28a58e30bb9
+ */
 exports.postFromMedium = async(req, res, next) => {
     try{
         const {url, dev, hash, dev_api, hash_api} = req.body;

controller/scheduleDevTo.controller.js

@@ -1,6 +1,27 @@
 const ScheduledPost = require('../models/schedulePost.model');
 const logger = require('../services/loggerService')
 
+/**
+ * @swagger
+ * components:
+ *  schemas:
+ *      ScheduledPost:
+ *          type: object
+ *          properties:
+ *              articleID:
+ *                  type: string
+ *                  description: Article identifier
+ *              APIkey:
+ *                  type: string
+ *                  description: Your API Key
+ *              publishTime:
+ *                  type: string
+ *                  description: Date time in ISO format
+ *          example:
+ *              articleID: 383924
+ *              APIkey: YOUR_API_KEY
+ *              publishTime: 2021-09-23T20:50:41.751Z
+ */
 exports.scheduleDevTo = async (req, res, next) => {
   const { APIkey, articleID, publishTime } = req.body;
   const schedulePost = new ScheduledPost({

index.js

@@ -7,6 +7,8 @@ const loggerService = require('./services/loggerService');
 const expressPinoLogger = require('express-pino-logger');
 const connectDB = require('./config/db');
 const cronJob = require("./services/cronJobs");
+const swaggerUI = require('swagger-ui-express');
+const swaggerJsdoc = require('swagger-jsdoc');
 
 cronJob();
 
@@ -26,5 +28,20 @@ app.use(express.json());
 app.use(cors());
 app.use('/api/v2', articleRoute);
 
+// Swagger specs
+const options = {
+    definition: {
+      openapi: '3.0.0',
+      info: {
+        title: 'IntegrateIO',
+        version: '1.0.0',
+      },
+    },
+    apis: ['./routes/*.js', './controller/*.js'], // files containing annotations as above
+};
+
+const specs = swaggerJsdoc(options);
+app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(specs));
+
 // connectDB();
 app.listen(PORT, () => console.log(`Server is running 🔥 on http://localhost:${PORT}`));

package.json

@@ -19,7 +19,9 @@
     "node-cron": "^3.0.0",
     "node-fetch": "^3.0.0",
     "pino": "^6.13.3",
-    "pino-pretty": "^7.0.1"
+    "pino-pretty": "^7.0.1",
+    "swagger-jsdoc": "^6.1.0",
+    "swagger-ui-express": "^4.3.0"
   },
   "devDependencies": {
     "nodemon": "^2.0.12"

routes/article.routes.js

@@ -5,13 +5,128 @@ const { postFromMedium } = require("../controller/postFromMedium.controller");
 const router = express.Router();
 const {scheduleDevTo} = require('../controller/scheduleDevTo.controller');
 
-
+/**
+ * @swagger
+ * /schedule:
+ *  post:
+ *      summary: Schedule a post
+ *      requestBody:
+ *          required: true
+ *          content:
+ *              application/json:
+ *                  schema:
+ *                      $ref: '#/components/schemas/ScheduledPost'
+ *      responses:
+ *          201:
+ *              description: Your post has been succesfully scheduled
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              response:
+ *                                  type: string
+ */
 router.post("/schedule", scheduleDevTo);
 
+/**
+ * @swagger
+ * /dev:
+ *  post:
+ *      summary: Post From Dev to Medium and/or Hashnode
+ *      requestBody:
+ *          required: true
+ *          content:
+ *              application/json:
+ *                  schema:
+ *                      $ref: '#/components/schemas/DevPost'
+ *      responses:
+ *          400:
+ *              description: An error occured while posting from Dev.to
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              Error:
+ *                                  type: string
+ *          201:
+ *              description: Your post has been succesfully created
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              Message:
+ *                                  type: string
+ */
 router.post('/dev', postFromDev);
 
+/**
+ * @swagger
+ * /medium:
+ *  post:
+ *      summary: Post From Medium to Dev and/or Hashnode
+ *      requestBody:
+ *          required: true
+ *          content:
+ *              application/json:
+ *                  schema:
+ *                      $ref: '#/components/schemas/MediumPost'
+ *      responses:
+ *          400:
+ *              description: An error occured while posting from Medium
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              Error:
+ *                                  type: string
+ *          201:
+ *              description: Your post has been succesfully created
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              Message:
+ *                                  type: string
+ */
 router.post('/medium', postFromMedium);
 
+
+/**
+ * @swagger
+ * /hash:
+ *  post:
+ *      summary: Post From Hashnode to Dev and/or Medium
+ *      requestBody:
+ *          required: true
+ *          content:
+ *              application/json:
+ *                  schema:
+ *                      $ref: '#/components/schemas/MediumPost'
+ *      responses:
+ *          400:
+ *              description: An error occured while posting from Hashnode
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              Error:
+ *                                  type: string
+ *          201:
+ *              description: Your post has been succesfully created
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              Message:
+ *                                  type: string
+ */
 router.post('/hash', postFromHash);
 
 module.exports = router;