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,5 +1,5 @@
 {
-  "name": "PlutoDevExpressAPI",
+	"name": "plutodev_express_api",
 	"version": "1.0.0",
 	"description": "",
 	"main": "index.js",
@@ -7,7 +7,8 @@
 		"start": "tsc && node ./dist/app.js",
 		"build": "tsc",
 		"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": "",
@@ -23,6 +24,8 @@
 		"guid-typescript": "^1.0.9",
 		"mariadb": "^2.5.3",
 		"random-words": "^1.1.1",
+		"swagger-jsdoc": "^6.1.0",
+		"swagger-ui-express": "^4.3.0",
 		"winston": "^3.3.3"
 	},
 	"devDependencies": {
@@ -31,6 +34,8 @@
 		"@types/debug": "^4.1.5",
 		"@types/express": "^4.17.11",
 		"@types/random-words": "^1.1.2",
+		"@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",

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();