API-35: Swagger documentation (!17)

Co-authored-by: Patrick Mueller <patrick@mueller-patrick.tech>
Reviewed-on: #17
Co-authored-by: Patrick Müller <patrick@plutodev.de>
Co-committed-by: Patrick Müller <patrick@plutodev.de>

.gitignore

@@ -2,3 +2,9 @@
 .idea
 **/*.iml
 .env
+
+# Build output
+dist/
+logs/
+node_modules/
+public/

app.ts

@@ -1,6 +1,8 @@
 import express from 'express';
 import * as http from 'http';
 import * as dotenv from 'dotenv';
+import swaggerUi from 'swagger-ui-express';
+import swaggerJSDoc from 'swagger-jsdoc';
 // Router imports
 import {partyPlanerRouter} from './src/models/partyplaner/PartyPlaner.router';
 import {highlightMarkerRouter} from './src/models/twitch-highlight-marker/HighlightMarker.router';
@@ -31,6 +33,39 @@ app.use(express.json());
 // Use CORS
 app.use(cors());
 
+// Swagger documentation
+const swaggerDefinition = {
+    openapi: '3.0.0',
+    info: {
+        title: 'Pluto Development REST API',
+        version: '2.0.0',
+        license: {
+            name: 'Licensed Under MIT',
+            url: 'https://spdx.org/licenses/MIT.html'
+        },
+        contact: {
+            name: 'Pluto Development',
+            url: 'https://www.pluto-development.de'
+        }
+    }
+};
+
+const options = {
+    swaggerDefinition,
+    // Paths to files containing OpenAPI definitions
+    apis: [
+        './src/models/**/*.router.ts'
+    ]
+};
+
+const swaggerSpec = swaggerJSDoc(options);
+
+app.use(
+    '/docs',
+    swaggerUi.serve,
+    swaggerUi.setup(swaggerSpec)
+);
+
 // Add routers
 app.use('/dhbw-service', dhbwServiceRouter);
 app.use('/twitch-highlight-marker', highlightMarkerRouter);

package.json

@@ -1,39 +1,44 @@
 {
-  "name": "PlutoDevExpressAPI",
+	"name": "plutodev_express_api",
-  "version": "1.0.0",
+	"version": "1.0.0",
-  "description": "",
+	"description": "",
-  "main": "index.js",
+	"main": "index.js",
-  "scripts": {
+	"scripts": {
-    "start": "tsc && node ./dist/app.js",
+		"start": "tsc && node ./dist/app.js",
-    "build": "tsc",
+		"build": "tsc",
-    "debug": "export DEBUG=* && npm run start",
+		"debug": "export DEBUG=* && npm run start",
-    "test": "echo \"Error: no test specified\" && exit 1"
+		"test": "echo \"Error: no test specified\" && exit 1",
-  },
+		"swagger": "tsoa spec"
-  "keywords": [],
+	},
-  "author": "",
+	"keywords": [],
-  "license": "ISC",
+	"author": "",
-  "dependencies": {
+	"license": "ISC",
-    "app-root-path": "^3.0.0",
+	"dependencies": {
-    "axios": "^0.24.0",
+		"app-root-path": "^3.0.0",
-    "bcrypt": "^5.0.1",
+		"axios": "^0.24.0",
-    "cors": "^2.8.5",
+		"bcrypt": "^5.0.1",
-    "debug": "^4.3.1",
+		"cors": "^2.8.5",
-    "dotenv": "^8.2.0",
+		"debug": "^4.3.1",
-    "express": "^4.17.1",
+		"dotenv": "^8.2.0",
-    "guid-typescript": "^1.0.9",
+		"express": "^4.17.1",
-    "mariadb": "^2.5.3",
+		"guid-typescript": "^1.0.9",
-    "random-words": "^1.1.1",
+		"mariadb": "^2.5.3",
-    "winston": "^3.3.3"
+		"random-words": "^1.1.1",
-  },
+		"swagger-jsdoc": "^6.1.0",
-  "devDependencies": {
+		"swagger-ui-express": "^4.3.0",
-    "@types/app-root-path": "^1.2.4",
+		"winston": "^3.3.3"
-    "@types/bcrypt": "^3.0.1",
+	},
-    "@types/debug": "^4.1.5",
+	"devDependencies": {
-    "@types/express": "^4.17.11",
+		"@types/app-root-path": "^1.2.4",
-    "@types/random-words": "^1.1.2",
+		"@types/bcrypt": "^3.0.1",
-    "@types/winston": "^2.4.4",
+		"@types/debug": "^4.1.5",
-    "source-map-support": "^0.5.19",
+		"@types/express": "^4.17.11",
-    "tslint": "^6.1.3",
+		"@types/random-words": "^1.1.2",
-    "typescript": "^4.1.5"
+		"@types/swagger-jsdoc": "^6.0.1",
-  }
+		"@types/swagger-ui-express": "^4.1.3",
+		"@types/winston": "^2.4.4",
+		"source-map-support": "^0.5.19",
+		"tslint": "^6.1.3",
+		"typescript": "^4.1.5"
+	}
 }

src/models/rapla-middleware/RaPlaMiddleware.router.ts

@@ -11,6 +11,54 @@ import * as icalgenerator from './icalgenerator/icalgenerator.service';
  */
 export const raPlaMiddlewareRouter = express.Router();
 
+/**
+ * @swagger
+ * /rapla-middleware:
+ *      get:
+ *          summary: Retrieve the adjusted RaPla .ics file
+ *          description: Downloads the current .ics file from DHBW servers, removes unwanted events and returns the file.
+ *              Required urls can be generated on https://rapla-middleware.p4ddy.com
+ *          tags:
+ *              - rapla-middleware
+ *          responses:
+ *              200:
+ *                  description: The .ics file
+ *              400:
+ *                  description: Wrong parameters, see response body for detailed information
+ *              500:
+ *                  description: A server error occured. Please try again. If this issue persists, contact the admin.
+ *          parameters:
+ *              -   in: query
+ *                  name: user
+ *                  required: true
+ *                  description: The user from RaPla, can be taken directly from the RaPla link
+ *                  schema:
+ *                      type: string
+ *              -   in: query
+ *                  name: file
+ *                  required: true
+ *                  description: The file from RaPla, can be taken directly from the RaPla link
+ *                  schema:
+ *                      type: string
+ *              -   in: query
+ *                  name: blockers
+ *                  required: false
+ *                  description: Whether to remove blockers from the .ics file
+ *                  schema:
+ *                      type: boolean [0,1]
+ *              -   in: query
+ *                  name: wahl
+ *                  required: false
+ *                  description: The chosen elective module which is not to be filtered out
+ *                  schema:
+ *                      type: number
+ *              -   in: query
+ *                  name: pflicht
+ *                  required: false
+ *                  description: The chosen profile module which is not to be filtered out
+ *                  schema:
+ *                      type: number
+ */
 raPlaMiddlewareRouter.get('/', async (req: Request, res: Response) => {
     try {
         let user = (req.query.user ?? '').toString();

tsconfig.json

@@ -1,10 +1,10 @@
 {
-  "compilerOptions": {
+	"compilerOptions": {
-    "target": "es2016",
+		"target": "es2016",
-    "module": "commonjs",
+		"module": "commonjs",
-    "outDir": "./dist",
+		"outDir": "./dist",
-    "strict": true,
+		"strict": true,
-    "esModuleInterop": true,
+		"esModuleInterop": true,
-    "inlineSourceMap": true
+		"inlineSourceMap": true
-  }
+	}
 }