Ovi · ueberBrot · May 13, 2025 · May 15, 2025
diff --git a/README.md b/README.md
@@ -8,6 +8,11 @@ Explore the detailed documentation at [DummyJSON/Docs](https://dummyjson.com/doc
 
 **New**: Now you can generate your own [custom responses](https://dummyjson.com/custom-response) from DummyJSON, [try it now!](https://dummyjson.com/custom-response)
 
+**New**: We now have an OpenAPI 3.1.0 specification available for DummyJSON!  
+You can find the `openapi.json` [here](https://dummyjson.com/api-docs/openapi.json).  
+Additionally, we’ve launched a fully interactive API UI powered by [Scalar](https://github.com/scalar/scalar) — making it even easier to explore and integrate DummyJSON into your projects. Check it out [here](https://dummyjson.com/api-docs)!
+
+
 ## Why DummyJSON?
 
 Ever felt bogged down by the complexities of setting up a backend just to fetch dummy data for your front-end project? Or perhaps you dreamt of a learning app where obtaining realistic data didn't involve navigating through convoluted public APIs and cumbersome registration processes. Well, say hello to DummyJSON!

diff --git a/package.json b/package.json
@@ -14,6 +14,7 @@
   "license": "MIT",
   "dependencies": {
     "@aws-sdk/client-s3": "^3.485.0",
+    "@scalar/express-api-reference": "^0.7.1",
     "axios": "^1.7.7",
     "color-convert": "^2.0.1",
     "compression": "^1.7.4",
@@ -34,6 +35,7 @@
     "on-finished": "^2.3.0",
     "on-headers": "^1.0.2",
     "sharp": "0.31.1",
+    "swagger-jsdoc": "^6.2.8",
     "uuid": "^10.0.0",
     "winston": "^3.14.2"
   },

diff --git a/public/img/icons/code.svg b/public/img/icons/code.svg
diff --git a/public/img/icons/doc.svg b/public/img/icons/doc.svg
diff --git a/src/middleware/openapi.js b/src/middleware/openapi.js
@@ -0,0 +1,55 @@
+const openapiSpec = require('../utils/openapi');
+const { log, logError } = require('../helpers/logger');
+const { version } = require('../../package.json');
+
+// We'll set up a middleware that will dynamically load the ESM module
+let apiReferenceMiddleware = null;
+
+const initializeApiReference = async () => {
+  try {
+    const scalarModule = await import('@scalar/express-api-reference');
+    const { apiReference } = scalarModule;
+
+    apiReferenceMiddleware = apiReference({
+      // URL to the OpenAPI specification
+      url: '/api-docs/openapi.json',
+      // URL to the API reference
+      cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
+      // Set theme, using the default theme
+      theme: 'default',
+      // Title for the API reference
+      title: 'DummyJSON API Reference',
+      // Version of the API
+      version,
+    });
+
+    log('Scalar API Reference initialized successfully');
+  } catch (error) {
+    logError('Failed to initialize Scalar API Reference:', { error });
+    // Provide a fallback middleware
+    apiReferenceMiddleware = (req, res) => {
+      res.status(500).json({ message: 'API documentation is currently unavailable' });
+    };
+  }
+};
+
+initializeApiReference();
+
+const serveOpenAPISpec = (req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+  res.send(openapiSpec);
+};
+
+// Middleware that checks if the API reference is loaded and uses it
+const serveApiReference = (req, res, next) => {
+  if (!apiReferenceMiddleware) {
+    return res.status(503).json({ message: 'API documentation is loading, please try again shortly' });
+  }
+
+  return apiReferenceMiddleware(req, res, next);
+};
+
+module.exports = {
+  serveOpenAPISpec,
+  serveApiReference,
+};
diff --git a/src/models/openapi-schemas/auth.js b/src/models/openapi-schemas/auth.js
@@ -0,0 +1,119 @@
+/**
+ * @openapi
+ * components:
+ *   securitySchemes:
+ *     bearerAuth:
+ *       type: http
+ *       scheme: bearer
+ *       bearerFormat: JWT
+ *       description: JWT token for authentication
+ *
+ *   schemas:
+ *     LoginRequest:
+ *       type: object
+ *       properties:
+ *         username:
+ *           type: string
+ *           description: Username for authentication
+ *           example: "emilys"
+ *         password:
+ *           type: string
+ *           description: Password for authentication
+ *           example: "emilyspass"
+ *         expiresInMins:
+ *           type: integer
+ *           description: Token expiration time in minutes
+ *           default: 60
+ *           example: 60
+ *       required:
+ *         - username
+ *         - password
+ *
+ *     RefreshTokenRequest:
+ *       type: object
+ *       properties:
+ *         refreshToken:
+ *           type: string
+ *           description: Refresh token obtained from login or previous token refresh
+ *           example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+ *         expiresInMins:
+ *           type: integer
+ *           description: Token expiration time in minutes
+ *           default: 60
+ *           example: 60
+ *       required:
+ *         - refreshToken
+ *
+ *     UserAuth:
+ *       type: object
+ *       properties:
+ *         id:
+ *           type: integer
+ *           description: User ID
+ *           example: 1
+ *         username:
+ *           type: string
+ *           description: Username of authenticated user
+ *           example: "emilys"
+ *         email:
+ *           type: string
+ *           description: Email of authenticated user
+ *           example: "emily.johnson@x.dummyjson.com"
+ *         firstName:
+ *           type: string
+ *           description: First name of user
+ *           example: "Emily"
 *         lastName:
+ *           type: string
+ *           description: Last name of user
+ *           example: "Johnson"
+ *         gender:
+ *           type: string
+ *           description: Gender of user
+ *           example: "female"
+ *         image:
+ *           type: string
+ *           description: Profile image URL
+ *           example: "https://dummyjson.com/icon/emilys/128"
+ *       required:
+ *         - id
+ *         - username
+ *         - email
+ *         - firstName
+ *         - lastName
+ *
+ *     AuthResponse:
+ *       allOf:
+ *         - $ref: '#/components/schemas/UserAuth'
+ *         - type: object
+ *           properties:
+ *             accessToken:
+ *               type: string
+ *               description: JWT Access Token
+ *               example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+ *             refreshToken:
+ *               type: string
+ *               description: JWT Refresh Token for obtaining a new access token
+ *               example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+ *           required:
+ *             - accessToken
+ *             - refreshToken
+ *
+ *     TokenResponse:
+ *       type: object
+ *       properties:
+ *         accessToken:
+ *           type: string
+ *           description: New JWT access token
+ *           example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+ *         refreshToken:
+ *           type: string
+ *           description: New JWT refresh token
+ *           example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+ *       required:
+ *         - accessToken
+ *         - refreshToken
+ */
+
+// Export the model schema (empty object since we're just using the JSDoc for OpenAPI)
+module.exports = {};