add: swagger-ui api

Author: whoisyurii

apps/backend/package.json

@@ -27,7 +27,9 @@
     "passport": "^0.7.0",
     "passport-jwt": "^4.0.1",
     "passport-local": "^1.0.0",
-    "pg": "^8.16.0"
+    "pg": "^8.16.0",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1"
   },
   "devDependencies": {
     "dotenv-cli": "^7.4.2",

apps/backend/src/index.js

@@ -2,27 +2,29 @@ import express from "express";
 import cors from "cors";
 import path from "path";
 import passport from "./middleware/passport.js";
-import { startTokenCleanupJob } from "./jobs/tokenCleanup.js";
 import authRoutes from "./routes/auth.js";
 import companyRoutes from "./routes/companies.js";
 import dashboardRoutes from "./routes/dashboard.js";
 import userRoutes from "./routes/users.js";
 import historyRoutes from "./routes/history.js";
+// swagger imports
+import swaggerJSDoc from 'swagger-jsdoc';
+import swaggerUI from 'swagger-ui-express';
+import swaggerSpec from "./swaggerSpec.js";
 
-// i use express for backend in this project
 const app = express();
 
 const PORT = process.env.PORT || 3001;
 
-// Middleware to enable CORS for all routes and parse JSON requests
+// middleware to enable CORS for all routes and parse JSON requests
 app.use(cors());
 app.use(express.json({ limit: '10mb' }));
 app.use(express.urlencoded({ extended: true, limit: '10mb' }));
 
-// Initialize Passport middleware
+// initialize Passport auth middleware
 app.use(passport.initialize());
 
-// Serve static files from public directory
+// serve static files from public directory
 app.use("/public", express.static(path.join(process.cwd(), "public")));
 
 // mount different api routes on specific paths
@@ -38,6 +40,8 @@ app.get("/api/health", (req, res) => {
   res.json({ status: "OK", timestamp: new Date().toISOString() });
 });
 
+app.use("/api-docs", swaggerUI.serve, swaggerUI.setup(swaggerSpec));
+
 app.listen(PORT, () => {
   console.log(`Server running on http://localhost:${PORT}`);
 });

apps/backend/src/routes/auth.js

@@ -13,6 +13,49 @@ import {
 
 const router = express.Router();
 
+/**
+ * @swagger
+ * /auth/login:
+ *   post:
+ *     summary: User login
+ *     tags:
+ *       - Authentication
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *               password:
+ *                 type: string
+ *             required:
+ *               - email
+ *               - password
+ *     responses:
+ *       200:
+ *         description: Login successful
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 user:
+ *                   type: object
+ *                 accessToken:
+ *                   type: string
+ *                 refreshToken:
+ *                   type: string
+ *                 expiresIn:
+ *                   type: string
+ *       401:
+ *         description: Invalid credentials
+ *       500:
+ *         description: Server error
+ */
 // Login через Passport Local Strategy
 router.post("/login", (req, res, next) => {
   authenticateLocal(req, res, async (err) => {
@@ -54,6 +97,55 @@ router.post("/login", (req, res, next) => {
   });
 });
 
+/**
+ * @swagger
+ * /auth/register:
+ *   post:
+ *     summary: User registration
+ *     tags:
+ *       - Authentication
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *               password:
+ *                 type: string
+ *               firstName:
+ *                 type: string
+ *               lastName:
+ *                 type: string
+ *             required:
+ *               - email
+ *               - password
+ *               - firstName
+ *               - lastName
+ *     responses:
+ *       201:
+ *         description: Registration successful
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 user:
+ *                   type: object
+ *                 accessToken:
+ *                   type: string
+ *                 refreshToken:
+ *                   type: string
+ *                 expiresIn:
+ *                   type: string
+ *       400:
+ *         description: User already exists
+ *       500:
+ *         description: Server error
+ */
 // Register with refresh token support
 router.post("/register", async (req, res) => {
   try {
@@ -107,6 +199,39 @@ router.post("/register", async (req, res) => {
   }
 });
 
+/**
+ * @swagger
+ * /auth/refresh:
+ *   post:
+ *     summary: Refresh access token
+ *     tags:
+ *       - Authentication
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               refreshToken:
+ *                 type: string
+ *             required:
+ *               - refreshToken
+ *     responses:
+ *       200:
+ *         description: Token refreshed successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 accessToken:
+ *                   type: string
+ *                 expiresIn:
+ *                   type: string
+ *       401:
+ *         description: Invalid refresh token
+ */
 // Refresh access token
 router.post("/refresh", async (req, res) => {
   try {
@@ -132,6 +257,38 @@ router.post("/refresh", async (req, res) => {
   }
 });
 
+/**
+ * @swagger
+ * /auth/logout:
+ *   post:
+ *     summary: User logout
+ *     tags:
+ *       - Authentication
+ *     security:
+ *       - bearerAuth: []
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               refreshToken:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Logout successful
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                 message:
+ *                   type: string
+ *       500:
+ *         description: Server error
+ */
 // Logout через Passport JWT
 router.post('/logout', authenticateJWT, async (req, res) => {
   try {
@@ -171,6 +328,44 @@ router.post('/logout', authenticateJWT, async (req, res) => {
   }
 });
 
+/**
+ * @swagger
+ * /auth/profile-passport:
+ *   get:
+ *     summary: Get user profile (Passport.js example)
+ *     description: Alternative endpoint to get user profile using Passport.js JWT authentication
+ *     tags:
+ *       - Authentication
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: User profile retrieved successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 user:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: integer
+ *                     email:
+ *                       type: string
+ *                     firstName:
+ *                       type: string
+ *                     lastName:
+ *                       type: string
+ *                     role:
+ *                       type: string
+ *                 message:
+ *                   type: string
+ *       401:
+ *         description: Unauthorized
+ *       500:
+ *         description: Server error
+ */
 // Alternative Passport.js protected route (example)
 router.get("/profile-passport", authenticateJWT, async (req, res) => {
   try {
@@ -184,6 +379,44 @@ router.get("/profile-passport", authenticateJWT, async (req, res) => {
   }
 });
 
+/**
+ * @swagger
+ * /auth/verify:
+ *   get:
+ *     summary: Verify JWT token
+ *     description: Verify if the provided JWT token is valid and return user information
+ *     tags:
+ *       - Authentication
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: Token is valid
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 user:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: integer
+ *                     email:
+ *                       type: string
+ *                     firstName:
+ *                       type: string
+ *                     lastName:
+ *                       type: string
+ *                     role:
+ *                       type: string
+ *                 authenticated:
+ *                   type: boolean
+ *       401:
+ *         description: Unauthorized
+ *       500:
+ *         description: Server error
+ */
 // Verify через Passport JWT
 router.get("/verify", authenticateJWT, async (req, res) => {
   try {
@@ -197,6 +430,45 @@ router.get("/verify", authenticateJWT, async (req, res) => {
   }
 });
 
+/**
+ * @swagger
+ * /auth/profile:
+ *   get:
+ *     summary: Get user profile
+ *     description: Get current authenticated user's profile information
+ *     tags:
+ *       - Authentication
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: User profile retrieved successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 id:
+ *                   type: integer
+ *                 email:
+ *                   type: string
+ *                 firstName:
+ *                   type: string
+ *                 lastName:
+ *                   type: string
+ *                 role:
+ *                   type: string
+ *                 createdAt:
+ *                   type: string
+ *                   format: date-time
+ *                 updatedAt:
+ *                   type: string
+ *                   format: date-time
+ *       401:
+ *         description: Unauthorized
+ *       500:
+ *         description: Server error
+ */
 // Profile через Passport JWT
 router.get("/profile", authenticateJWT, async (req, res) => {
   try {