Merge pull request #20 from surhud004/feat-swagger

Feat swagger documentation

README.md

@@ -10,6 +10,8 @@ Visit https://foodish-api.com/
 
 ## API Documentation
 
+#### OpenAPI Specification Swagger v3: https://foodish-api.com/api-docs
+
 Base URL for all endpoints https://foodish-api.com/
 
 _The response time will likely be a few seconds long on the first request, because this app is running on a free instance. Subsequent requests will behave as normal._
@@ -77,6 +79,7 @@ Please read the [CONTRIBUTING](https://github.com/surhud004/Foodish/blob/main/CO
 ## Credits
 
 Foodish would not be possible without the work of:
+
 - [Rajaraman Ekambaram](https://github.com/Rtech2014) for providing the initial Foodish image database via [Kaggle](https://www.kaggle.com/datasets).
 - [RitaE](https://pixabay.com/users/ritae-19628/) for providing some additional Foodish images via [Pixabay](https://pixabay.com/).
 

app.js

@@ -1,6 +1,8 @@
 const express = require('express');
 const fs = require('fs');
 const cors = require('cors');
+const swaggerUI = require('swagger-ui-express');
+const swaggerJSON = require('./docs/swagger-api.json');
 
 const PORT = process.env.PORT || 3000;
 
@@ -11,6 +13,8 @@ app.use('/images', express.static(`${__dirname}/public/assets/images`));
 app.use('/assets', express.static(`${__dirname}/public`));
 app.set('view engine', 'ejs');
 
+app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerJSON));
+
 const MENU_DB = ['biryani', 'burger', 'butter-chicken', 'dessert', 'dosa', 'idly', 'pasta', 'pizza', 'rice', 'samosa'];
 
 const getImageCount = () => {
@@ -35,6 +39,7 @@ const getImageCount = () => {
 
 // UI CALLS
 app.get('/', (req, res) => {
+  // #swagger.ignore = true
   // random number generator within MENU_DB array range
   const randomSelector = Math.floor(Math.random() * MENU_DB.length);
 
@@ -59,6 +64,7 @@ app.get('/', (req, res) => {
 });
 
 app.get('/images/:food', (req, res) => {
+  // #swagger.ignore = true
   // food is pizza
   const { food } = req.params;
 
@@ -110,6 +116,19 @@ app.get('/images/:food', (req, res) => {
 
 // API CALLS
 app.get('/api', (req, res) => {
+  // #swagger.tags = ['API']
+  // #swagger.description = 'Get a random food dish image.'
+  /* #swagger.responses[200] = {
+            description: "OK",
+            content: {
+                "application/json": {
+                    example:{
+                        image: "https://foodish-api.com/images/burger/burger101.jpg"
+                    }
+                }           
+            }
+        }   
+    */
   try {
     const randomSelector = Math.floor(Math.random() * MENU_DB.length);
     const anyRandomFood = MENU_DB[randomSelector];
@@ -126,6 +145,21 @@ app.get('/api', (req, res) => {
 });
 
 app.get('/api/images/:food', (req, res) => {
+  // #swagger.tags = ['API']
+  // #swagger.description = 'Get a random food dish image from "food" category.'
+  // #swagger.parameters['food'] = { description: 'Required food category.' }
+  // #swagger.parameters['keyword'] = { description: 'Optional filter for food category image. (Beta version: only works for pizza food category. More details: https://github.com/surhud004/Foodish/discussions/14).' }
+  /* #swagger.responses[200] = {
+            description: "OK",
+            content: {
+                "application/json": {
+                    example:{
+                        image: "https://foodish-api.com/images/burger/burger101.jpg"
+                    }
+                }           
+            }
+        }   
+    */
   try {
     const { food } = req.params;
     let finalFood;

docs/swagger-api.json

@@ -0,0 +1,84 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "Foodish API",
+    "description": "A Node.js/Express.js REST API to GET a random picture of food dishes."
+  },
+  "servers": [
+    {
+      "url": "https://foodish-api.com",
+      "description": "Foodish API server"
+    }
+  ],
+  "paths": {
+    "/api": {
+      "get": {
+        "tags": [
+          "API"
+        ],
+        "description": "Get a random food dish image.",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "example": {
+                  "image": "https://foodish-api.com/images/burger/burger101.jpg"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error"
+          }
+        }
+      }
+    },
+    "/api/images/{food}": {
+      "get": {
+        "tags": [
+          "API"
+        ],
+        "description": "Get a random food dish image from \"food\" category.",
+        "parameters": [
+          {
+            "name": "food",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Required food category."
+          },
+          {
+            "name": "keyword",
+            "description": "Optional filter for food category image. (Beta version: only works for pizza food category. More details: https://github.com/surhud004/Foodish/discussions/14).",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "example": {
+                  "image": "https://foodish-api.com/images/burger/burger101.jpg"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found"
+          },
+          "500": {
+            "description": "Internal Server Error"
+          }
+        }
+      }
+    }
+  }
+}

docs/swagger.js

@@ -0,0 +1,20 @@
+const swaggerAutogen = require('swagger-autogen')({ openapi: '3.0.0' });
+
+const doc = {
+  info: {
+    version: '1.0.0',
+    title: 'Foodish API',
+    description: 'A Node.js/Express.js REST API to GET a random picture of food dishes.'
+  },
+  servers: [
+    {
+      url: 'https://foodish-api.com',
+      description: 'Foodish API server'
+    }
+  ]
+};
+
+const outputFile = './swagger-api.json';
+const routes = ['../app.js'];
+
+swaggerAutogen(outputFile, routes, doc);