feat: update OpenAPI specification to version 3.0.4, enhance API endpoints, and improve response descriptions

services/data-manager/openapi.yml

@@ -1,10 +1,12 @@
-openapi: 3.0.0
+openapi: 3.0.4
 info:
   title: HTWKalendar API
-  version: 1.0.1
+  version: 1.0.2
 servers:
-  - url: https://htwkalendar.de
+  - url: https://cal.htwk-leipzig.de
     description: Production server
+  - url: https://dev.cal.fsr.imn.htwk-leipzig.de
+    description: Development server
   - url: http://localhost:8090
     description: Local server
 paths:
@@ -16,6 +18,31 @@ paths:
       responses:
         '200':
           description: Successful response
+
+  /api/fetch/daily/events:
+    get:
+      summary: Fetch daily events from remote
+      security:
+        - ApiKeyAuth: []
+      responses:
+        '200':
+          description: Successful response
+
+  /api/fetch/group:
+    get:
+      summary: Fetch or update modules for a seminar group
+      security:
+        - ApiKeyAuth: []
+      parameters:
+        - name: seminarGroup
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+
   /api/fetch/groups:
     get:
       summary: Fetch Seminar Groups
@@ -24,6 +51,7 @@ paths:
       responses:
         '200':
           description: Successful response
+
   /api/fetch/sports:
     get:
       summary: Fetch Sport Events from HTWK Leipzig
@@ -32,91 +60,178 @@ paths:
       responses:
         '200':
           description: Successful response
+
   /api/modules:
+    get:
+      summary: Get all modules distinct
+      responses:
+        '200':
+          description: Successful response
     delete:
-        summary: Delete Module
+      summary: Delete all events
-        security:
+      security:
-            - ApiKeyAuth: []
+        - ApiKeyAuth: []
-        responses:
+      responses:
-          '200':
+        '200':
-            description: Successful response
+          description: Successful response
+
   /api/rooms:
     get:
       summary: Get Rooms
       responses:
         '200':
           description: Successful response
-  /api/rooms/free:
+
-    get:
-      summary: Get Free Rooms
-      parameters:
-        - name: from
-          in: query
-          description: start date
-          example: "2006-01-02T15:04:05Z"
-          required: true
-          schema:
-            type: string
-        - name: to
-          in: query
-          description: end date
-          example: "2006-01-02T15:04:05Z"
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Successful response
   /api/schedule/day:
     get:
       summary: Get Day Schedule
       parameters:
         - name: room
           in: query
-          description: room
-          example: "LN006-H"
           required: true
           schema:
             type: string
         - name: date
           in: query
-          description: date
-          example: "2023-11-26"
           required: true
           schema:
             type: string
       responses:
         '200':
           description: Successful response
+
   /api/schedule:
     get:
       summary: Get Schedule
       parameters:
         - name: room
           in: query
-          description: room
-          example: "LN006-H"
           required: true
           schema:
             type: string
         - name: from
           in: query
-          description: date
+          description: start date
-          example: "2023-11-26"
           required: true
           schema:
             type: string
         - name: to
           in: query
-          description: date
+          description: end date
-          example: "2023-11-30"
+          required: true
+          schema:
+            type: string
+        - name: mapped
+          in: query
+          description: optional mapping flag
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+
+  /api/course/modules:
+    get:
+      summary: Get Modules for Course
+      parameters:
+        - name: course
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: semester
+          in: query
           required: true
           schema:
             type: string
       responses:
         '200':
           description: Successful response
-  /api/createFeed:
+
+  /api/module:
+    get:
+      summary: Get Module
+      parameters:
+        - name: uuid
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+
+  /api/courses:
+    get:
+      summary: Get courses or courses by semester
+      parameters:
+        - name: semester
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+
+  /api/rooms/free:
+    get:
+      summary: Get Free Rooms
+      parameters:
+        - name: from
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: to
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+
+  /api/courses/events:
+    get:
+      summary: Get Courses that have Events for specific semester
+      parameters:
+        - name: semester
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+
+  /api/events/types:
+    get:
+      summary: Get event types
+      responses:
+        '200':
+          description: Successful response
+
+  /api/events:
+    delete:
+      summary: Delete events for a course and semester
+      security:
+        - ApiKeyAuth: []
+      parameters:
+        - name: course
+          in: query
+          schema:
+            type: string
+        - name: semester
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+
+  /api/feed:
     post:
       summary: Create iCal Feed
       requestBody:
@@ -125,103 +240,42 @@ paths:
             schema:
               type: array
               items:
-                $ref: '#/components/schemas/Module'
+                $ref: '#/components/schemas/FeedCollection'
-              required:
-                - name
-                - modules
       responses:
         '200':
           description: Successful response
-  /api/feed:
+
-    get:
+  /api/feeds/{token}:
-      summary: Get iCal Feed for calendar
+    delete:
+      summary: Delete iCal feed
       parameters:
         - name: token
-          in: query
+          in: path
-          description: calendar token
           required: true
-          example: "ldluwzg3e73ffxq"
           schema:
             type: string
       responses:
         '200':
           description: Successful response
-  /api/course/modules:
+
-    get:
+  /api/collections/feeds/records/{id}: 
-      summary: Get Modules for Course
-      parameters:
-        - name: course
-          in: query
-          description: course
-          required: true
-          example: "Software Engineering"
-          schema:
-            type: string
-        - name: semester
-          in: query
-          description: semester
-          required: true
-          example: "ws"
-          schema:
-              type: string
-      responses:
-        '200':
-          description: Successful response
-  /api/module:
-    get:
-      summary: Get Module
-      parameters:
-        - name: uuid
-          in: query
-          description: uuid
-          required: true
-          example: "d0b3a0e0-2f1a-4e1a-8b0a-0b9e1a0b9e1a"
-          schema:
-              type: string
-      responses:
-        '200':
-          description: Successful response
-  /api/courses:
-    get:
-      summary: Get Courses
-      responses:
-        '200':
-          description: Successful response
-  /api/courses/events:
-    get:
-      summary: Get Courses that have Events for specific semester
-      parameters:
-        - name: semester
-          in: query
-          description: semester
-          required: true
-          example: "ws"
-          schema:
-              type: string
-      responses:
-        '200':
-          description: Successful response
-  /api/collections/feeds/records/{id}:
     get:
+      tags:
+        - iCal
+        - Feed
       summary: Get Modules selected for iCal feed
       parameters:
         - name: id
           in: path
-          description: calendar token
           required: true
           schema:
             type: string
+            format: uuid
+          description: calendar token
       responses:
         '200':
           description: Successful response
-  /api/events:
+
-    delete:
-        summary: Delete Event
-        security:
-            - ApiKeyAuth: []
-        responses:
-          '200':
-            description: Successful response
   /api/feeds/migrate:
     get:
       summary: Migrates all iCal Feeds in the database to the new format
@@ -230,36 +284,60 @@ paths:
       responses:
         '200':
           description: Successful response
+
+
+
+
+
 security:
   - ApiKeyAuth: []
 components:
-    securitySchemes:
+  securitySchemes:
-      ApiKeyAuth:
+    ApiKeyAuth:
-        type: apiKey
+      type: apiKey
-        in: header
+      in: header
-        name: Authorization
+      name: Authorization
-    schemas:
+  schemas:
-      Module:
+    Module:
-        type: object
+      type: object
-        properties:
+      properties:
-          name:
+        name:
+          type: string
+        uuid:
+          type: string
+          format: uuid
+        course:
+          type: string
+        userDefinedName:
+          type: string
+        prof:
+          type: string
+        semester:
+          type: string
+        reminder:
+          type: boolean
+        events:
+          type: array
+          items:
             type: string
-            description: name
+    FeedCollection:
-            example: "Software Engineering"
+      type: object
-          uuid:
+      properties:
-            type: string
+        name:
-            format: uuid
+          type: string
-          course:
+        uuid:
-            type: string
+          type: string
-          userDefinedName:
+        course:
-            type: string
+          type: string
-          prof:
+        userDefinedName:
-            type: string
+          type: string
-          semester:
+        prof:
-            type: string
+          type: string
-          reminder:
+        semester:
-            type: boolean
+          type: string
-          events:
+        reminder:
-            type: array
+          type: boolean
-            items:
+        events:
-              type: string
+          type: array
+          items:
+            type: string