Merge pull request #20 from roydekleijn/swagger

added Swagger to the api

Author: Darshan-Chauhan

README.md

@@ -37,3 +37,7 @@ yarn dev
 ```
 
 visit `http://localhost:3000/`
+
+### Open Swagger UI
+
+visit `http://localhost:3000/swagger`

package.json

@@ -22,6 +22,7 @@
     "next": "10.0.1",
     "next-compose-plugins": "^2.2.1",
     "next-optimized-images": "^2.6.2",
+    "next-swagger-doc": "^0.1.9",
     "postcss-import": "^13.0.0",
     "postcss-preset-env": "^6.7.0",
     "prop-types": "15.7.2",
@@ -34,6 +35,7 @@
     "redux-thunk": "^2.3.0",
     "sass": "^1.29.0",
     "store2": "^2.12.0",
+    "swagger-ui-react": "^3.52.3",
     "tailwindcss": "^1.9.6",
     "webpack": "^4.0.0"
   }

pages/api/checkout.js

@@ -1,11 +1,27 @@
 import { isValidUser } from '../../src/constants/users';
 
+/**
+ * @swagger
+ * /api/checkout:
+ *   get:
+ *     description: Validate if the logged in user is allowed to checkout products.
+ *     parameters:
+ *     - in: query
+ *       name: userName
+ *       required: false
+ *       description:  Name of the signed in user.
+ *     responses:
+ *       200:
+ *         description: userName is valid.
+ *       422:
+ *         description: userName is invalid.
+ */
 export default (req, res) => {
   const userName = req.body['userName'];
   if (isValidUser(userName)) {
     res.statusCode = 200;
     res.json({});
-  } else {    
+  } else {
     res.statusCode = 422;
     res.json({ });
   }

pages/api/doc.js

@@ -0,0 +1,9 @@
+import { withSwagger } from 'next-swagger-doc';
+
+const swaggerHandler = withSwagger({
+  openApiVersion: '3.0.0',
+  title: 'BstackDemo API',
+  version: '1.0.0',
+  apiFolder: 'pages/api',
+});
+export default swaggerHandler();

pages/api/offers.js

@@ -1,5 +1,29 @@
 import offersData from '../../src/constants/offers.json';
 
+/**
+ * @swagger
+ * /api/offers:
+ *   get:
+ *     description: Returns all available offers on products.
+ *     parameters:
+ *     - in: query
+ *       name: userName
+ *       required: false
+ *       description:  Name of the signed in user.
+ *     - in: query
+ *       name: latitude
+ *       required: false
+ *       description:  latitude of the location.
+ *     - in: query
+ *       name: longitude
+ *       required: false
+ *       description:  longitude of the location.
+ *     responses:
+ *       200:
+ *         description: List of all offers for a specific location.
+ *       404:
+ *         description: City name could not be determined.
+ */
 export default (req, res) => {
   const userName = req.query['userName'];
   const latitude = parseInt(req.query['latitude'], 10);
@@ -35,7 +59,7 @@ export default (req, res) => {
     const hasMatchingLon = longitude >= cityCoords.lon - 3 && longitude <= cityCoords.lon + 3;
     if(hasMatchingLat && hasMatchingLon) {
       city = cityName;
-    } 
+    }
   });
 
   if (city) {

pages/api/orders.js

@@ -1,5 +1,21 @@
 import ordersData from '../../src/constants/orders.json';
 
+/**
+ * @swagger
+ * /api/orders:
+ *   get:
+ *     description: Returns all orders associated with the logged in user.
+ *     parameters:
+ *     - in: query
+ *       name: userName
+ *       required: false
+ *       description:  Name of the signed in user. If the user name is set to existing_orders_user, the response returns all orders.
+ *     responses:
+ *       200:
+ *         description: List of all orders.
+ *       404:
+ *         description: No orders found
+ */
 export default (req, res) => {
   const userName = req.query['userName'];
 

pages/api/products.js

@@ -1,5 +1,19 @@
 import productsData from '../../src/constants/products.json';
 
+/**
+ * @swagger
+ * /api/products:
+ *   get:
+ *     description: Returns all products
+ *     parameters:
+ *     - in: query
+ *       name: userName
+ *       required: false
+ *       description:  Name of the signed in user. If the user name is set to fav_user , the response returns the first 5 products marked as favorite.
+ *     responses:
+ *       200:
+ *         description: List of products
+ */
 export default (req, res) => {
   const userName = req.query['userName'];
 

pages/api/signin.js

@@ -1,5 +1,28 @@
 import { isValidUser, isValidPassword, isLockedUser } from '../../src/constants/users';
 
+/**
+ * @swagger
+ * /api/signin:
+ *   post:
+ *     description: Authenticate and sign in the user.
+ *     requestBody:
+ *        description: Sign in credentials that you want to authenticate.
+ *        required: true
+ *        content:
+ *          application/json:
+ *            schema:
+ *              type: object
+ *              properties:
+ *                userName:
+ *                  type: string
+ *                password:
+ *                  type: string
+ *     responses:
+ *       200:
+ *         description: Successful signin
+ *       422:
+ *         description: User credentials cannot be processed. Check if the credentials are incorrect or if your account is locked.
+ */
 export default (req, res) => {
   const userName = req.body['userName'];
   const password = req.body['password'];
@@ -19,7 +42,7 @@ export default (req, res) => {
     if (isLockedUser(userName)) {
       errorMessage = 'Your account has been locked.'
     }
-    
+
     res.statusCode = 422;
     res.json({ errorMessage });
   }

pages/swagger/index.jsx

@@ -0,0 +1,20 @@
+import Head from 'next/head';
+
+import SwaggerUI from 'swagger-ui-react';
+import 'swagger-ui-react/swagger-ui.css';
+
+const Swagger = () => {
+
+  return (
+      <div>
+        <Head>
+          <title>Bstack Demo API</title>
+          <meta name="description" content="Generated by create next app" />
+          <link rel="icon" href="/favicon.ico" />
+        </Head>
+        <SwaggerUI url="/api/doc" />
+      </div>
+  );
+};
+
+export default Swagger;