Set up swagger for api documentation

Author: nicolelim02

backend/user-service/app.ts

@@ -1,9 +1,15 @@
 import express, { Request, Response, NextFunction } from "express";
 import cors from "cors";
+import fs from "fs";
+import yaml from "yaml";
+import swaggerUi from "swagger-ui-express";
 
 import userRoutes from "./routes/user-routes.js";
 import authRoutes from "./routes/auth-routes.js";
 
+const file = fs.readFileSync("./swagger.yml", "utf-8");
+const swaggerDocument = yaml.parse(file);
+
 const app = express();
 
 app.use(express.urlencoded({ extended: true }));
@@ -30,9 +36,9 @@ app.use((req: Request, res: Response, next: NextFunction) => {
   next();
 });
 
-app.use("/users", userRoutes);
-app.use("/auth", authRoutes);
-
+app.use("/api/users", userRoutes);
+app.use("/api/auth", authRoutes);
+app.use("/docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));
 app.get("/", (req: Request, res: Response, next: NextFunction) => {
   console.log("Sending Greetings!");
   res.json({

backend/user-service/package-lock.json

@@ -19,6 +19,7 @@
     "@types/express": "^4.17.21",
     "@types/jsonwebtoken": "^9.0.7",
     "@types/node": "^22.5.5",
+    "@types/swagger-ui-express": "^4.1.6",
     "@types/validator": "^13.12.2",
     "nodemon": "^3.1.4",
     "tsx": "^4.19.1",
@@ -32,6 +33,8 @@
     "express": "^4.19.2",
     "jsonwebtoken": "^9.0.2",
     "mongoose": "^8.5.4",
-    "validator": "^13.12.0"
+    "swagger-ui-express": "^5.0.1",
+    "validator": "^13.12.0",
+    "yaml": "^2.5.1"
   }
 }

backend/user-service/package.json

@@ -0,0 +1,183 @@
+openapi: 3.0.0
+
+info:
+  title: User Service
+  version: 1.0.0
+
+components:
+  schemas:
+    User:
+      properties:
+        username:
+          type: string
+          required: true
+        firstName:
+          type: string
+          required: true
+        lastName:
+          type: string
+          required: true
+        email:
+          type: string
+          required: true
+        isAdmin:
+          type: boolean
+          required: true
+          default: false
+        biography:
+          type: string
+          required: false
+        profilePictureUrl:
+          type: string
+          required: false
+        password:
+          type: string
+          required: true
+    UserResponse:
+      properties:
+        id:
+          type: string
+          required: true
+        username:
+          type: string
+          required: true
+        firstName:
+          type: string
+          required: true
+        lastName:
+          type: string
+          required: true
+        email:
+          type: string
+          required: true
+        isAdmin:
+          type: boolean
+          required: true
+          default: false
+        biography:
+          type: string
+          required: false
+        profilePictureUrl:
+          type: string
+          required: false
+        createdAt:
+          type: string
+          required: true
+    ErrorResponse:
+      properties:
+        message:
+          type: string
+
+paths:
+  /:
+    get:
+      tags:
+        - root
+      summary: Ping the server
+      responses:
+        200:
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    description: Message
+  /api/users:
+    post:
+      tags:
+        - users
+      summary: Creates a new user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/User"
+      responses:
+        201:
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserResponse"
+        400:
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        409:
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+    get:
+      tags:
+        - users
+      summary: Get all users
+      responses:
+        200:
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/UserResponse"
+  /api/users/{id}:
+    get:
+      summary: Get a user by id
+      tags:
+        - users
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserResponse"
+        404:
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+    patch:
+      summary: Update a user's particulars
+      tags:
+        - users
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+    delete:
+      summary: Delete a user account
+      tags:
+        - users
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+  /api/auth/login:
+    post:
+      summary: Login
+      tags:
+        - auth
+  /api/auth/verify-token:
+    get:
+      summary: Verify token
+      tags:
+        - auth