PIX-31: add openapi description of the api, add swagger-ui-express to see the definition of the api on the endpoint /api-docs

Author: AndreaZavatta

server/package.json

@@ -15,13 +15,17 @@
 		"express": "^4.21.2",
 		"jsonwebtoken": "^9.0.3",
 		"mongoose": "^8.9.5",
-		"socket.io": "^4.8.1"
+		"socket.io": "^4.8.1",
+		"swagger-ui-express": "^5.0.1",
+		"yamljs": "^0.3.0"
 	},
 	"devDependencies": {
 		"@types/cors": "^2.8.17",
 		"@types/express": "^4.17.21",
 		"@types/jsonwebtoken": "^9.0.7",
 		"@types/node": "^20.10.6",
+		"@types/swagger-ui-express": "^4.1.8",
+		"@types/yamljs": "^0.2.34",
 		"nodemon": "^3.1.9",
 		"ts-node": "^10.9.2",
 		"tsx": "^4.7.0",
@@ -33,4 +37,4 @@
 	"keywords": [],
 	"author": "",
 	"license": "ISC"
-}
+}

server/pixie-api.yaml

@@ -0,0 +1,91 @@
+openapi: 3.1.0
+info:
+  title: Pixie API
+  version: 1.0.0
+  description: API for Pixie application, providing user authentication and management.
+servers:
+  - url: http://localhost:3000/api
+    description: Local server
+paths:
+  /login:
+    post:
+      summary: User login
+      description: Authenticates a user or registers a new one if not found.
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+                  example: "playerOne"
+              required:
+                - username
+      responses:
+        '200':
+          description: Successful login
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LoginResponse'
+        '400':
+          description: Bad Request (Missing username)
+  /users:
+    get:
+      summary: Get all users
+      description: Retrieve a list of all users. Requires authentication.
+      tags:
+        - Users
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: List of users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/UserSummary'
+        '401':
+          description: Unauthorized (Missing token)
+        '403':
+          description: Forbidden (Invalid token)
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    UserSummary:
+      type: object
+      properties:
+        username:
+          type: string
+          example: "playerOne"
+        isAdmin:
+          type: boolean
+          example: false
+        _id:
+          type: string
+          example: "60d0fe4f5311236168a109ca"
+    LoginResponse:
+      type: object
+      properties:
+        username:
+          type: string
+          example: "playerOne"
+        id:
+          type: string
+          example: "60d0fe4f5311236168a109ca"
+        token:
+          type: string
+          description: JWT token for authentication
+        isNewUser:
+          type: boolean
+          description: True if a new account was created

server/src/db/connect.ts

@@ -1,5 +1,5 @@
 import mongoose from "mongoose"
-import { seedUsers } from "./seed"
+import { seedUsers } from "./seed.js"
 
 const MONGO_URI = process.env.MONGO_URI || "mongodb://localhost:27017/pixie"
 

server/src/db/seed.ts

@@ -1,4 +1,4 @@
-import { User } from "../models/User"
+import { User } from "../models/User.js"
 
 export const seedUsers = async (): Promise<void> => {
 	const users = [

server/src/index.ts

@@ -33,6 +33,12 @@ import { errorHandler } from "./middlewares/errorMiddleware.js";
 // API Routes (REST)
 app.use("/api", router);
 
+// Swagger UI
+import swaggerUi from "swagger-ui-express";
+import YAML from "yamljs";
+const swaggerDocument = YAML.load("./pixie-api.yaml");
+app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));
+
 // Global Error Handler
 app.use(errorHandler);