feat: Implement personal events

Issue #12

README.md

@@ -22,3 +22,20 @@ OpenAPI documentation of the modulplaner API
 - `Semester`: This term is too limiting compared to `Term`, as it always refers to 6 months. Some schools will use different lengths for their terms.
 - `Degree`: We should use the term `Course`, as the degree is what you receive when completing a `Course`.
 - `Teacher`: Use `Lecturer` instead, as this is the common term used by universities.
+
+### Types used
+
+The numeric fields have an additional `format` tag assigned:
+
+- `u8`: Unsigned 8 bit (0 - 255)
+- `u16`: Unsigned 16 bit (0 - 65'535)
+- `u…`: Unsigned … bit
+
+
+- `i8`: Signed 8 bit (-128 - 127)
+- `i16`: Signed 16 bit (-32'768 - 32'767)
+- `i…`: Signed … bit
+
+
+- `f32`: 32 bit floating point number
+- `f64`: 64 bit floating point number

src/components/enums/weekday.yaml

@@ -1,5 +1,5 @@
 type: integer
-format: int8
+format: u8
 description: The various weekdays
 oneOf:
   - title: Monday

src/components/responses/api/me/personal-events-get-200.yaml

@@ -0,0 +1,10 @@
+description: OK
+content:
+  application/json:
+    schema:
+      type: array
+      items:
+        $ref: ../../../schemas/api/personal-event.yaml
+    # TODO
+    # example:
+    #   $ref: ../../../examples/api/me/personal-events.yaml

src/components/schemas/api/class.yaml

@@ -7,11 +7,11 @@ properties:
   from:
     description: Start time of the module, in seconds since midnight
     type: integer
-    format: int32
+    format: u32
   to:
     description: End time of the module, in seconds since midnight
     type: integer
-    format: int32
+    format: u32
   class:
     description: Name of the class this module is part of
     type: string
@@ -37,7 +37,7 @@ properties:
     type: array
     items:
       type: integer
-      format: int16
+      format: u16
   degree_prg:
     description: Name of the degree program this module is part of
     type: string

src/components/schemas/api/me-enrolment.yaml

@@ -21,32 +21,22 @@ properties:
         const: failed
         description: The student failed the module
   course_pk:
-    description: The governing course for this enrolment
-    type: number
-    format: i32
+    $ref: ../relations/course.yaml
   term_pk:
-    description: The term, in which this enrolment took place in
-    type: number
-    format: i32
+    $ref: ../relations/term.yaml
   ects:
-    description: The number of ECTS awarded
-    type: number
-    format: f32
+    $ref: ../common/ects.yaml
   mark:
-    description: The achieved mark
-    type: number
-    format: f32
+    $ref: ../common/mark.yaml
   module_pk:
-    description: The module, which the student enrolled in
-    type: number
-    format: i32
+    $ref: ../relations/module.yaml
   start_date:
     description: When this enrolment started (UNIX timestamp in seconds)
-    type: number
-    format: i64
+    type: integer
+    format: u64
   end_date:
     description: When this enrolment ended (UNIX timestamp in seconds)
-    format: i64
+    format: u64
 required:
   - status
   - course_pk

src/components/schemas/api/me-module.yaml

@@ -2,18 +2,11 @@ type: object
 description: A simplified module that is tailored to the `/me` endpoints
 properties:
   module_pk:
-    type: number
-    format: i32
-    description: The module
-    example: an1
+    $ref: ../relations/module.yaml
   ects:
-    type: number
-    format: f32
-    description: How many ects were awarded
+    $ref: ../common/ects.yaml
   mark:
-    type: number
-    format: f32
-    description: The (numerical) mark that was achieved
+    $ref: ../common/mark.yaml
 required:
   - module_pk
   - ects

src/components/schemas/api/me.yaml

@@ -8,7 +8,7 @@ properties:
     description: Surname of the student
   cadastral_number:
     type: integer
-    format: int64
+    format: u64
     description: Unique enrolment number for a student
   credited_modules:
     type: array
@@ -19,12 +19,10 @@ properties:
     items:
       properties:
         ects:
-          type: number
-          format: f32
-          description: The number of ECTS awarded
+          $ref: ../common/ects.yaml
         reason:
           type: string
-          description: The reason for receiving the credits
+          description: A human readable reason for receiving the credits
       required:
         - ects
         - reason

src/components/schemas/api/module-history.yaml

@@ -18,11 +18,11 @@ items:
     from:
       description: Start time of the module, in seconds since midnight
       type: integer
-      format: int32
+      format: u32
     to:
       description: End time of the module, in seconds since midnight
       type: integer
-      format: int32
+      format: u32
     lecturers:
       description: List of lecturers teaching this module
       type: array
@@ -41,7 +41,7 @@ items:
       type: array
       items:
         type: integer
-        format: int16
+        format: u16
     pk:
       description: A unique ID for this module and the time it is taught
       type: string

src/components/schemas/api/module.yaml

@@ -26,7 +26,7 @@ properties:
       - "null"
     items:
       type: integer
-      format: int32
+      format: u32
   ects:
     description: The number of ECTS this module awards upon completion.
     type:

src/components/schemas/api/personal-event.yaml

@@ -0,0 +1,57 @@
+type: object
+description: A personal event entry for a single user
+properties:
+  term_pk:
+    $ref: ../relations/term.yaml
+  title:
+    description: The title of the personal event
+    type: string
+  location:
+    description: The location of the private event
+    type: string
+  description:
+    description: Any additional information / descriptions the user might want to add
+    type: string
+  travel_time_before:
+    description: How long we need to travel to get to our private event (in seconds)
+    type: integer
+    format: u16
+  travel_time_after:
+    description: How long we need to travel to get to back from our private event (in seconds)
+    type: integer
+    format: u16
+  start_time:
+    description: When the actual event starts (Unix timestamp in seconds)
+    type: integer
+    format: u64
+  end_time:
+    description: When the actual event ends (Unix timestamp in seconds)
+    type: integer
+    format: u64
+  repeat_every:
+    description: Repeat this event every n <repeat_unit>
+    type: integer
+    format: u8
+  repeat_unit:
+    description: The unit of how often to repeat this event
+    type: string
+    oneOf:
+      - id: once
+        const: once
+      - id: days
+        const: days
+      - id: weeks
+        const: weeks
+      - id: months
+        const: months
+required:
+  - term_pk
+  - title
+  - location
+  - description
+  - travel_time_before
+  - travel_time_after
+  - start_time
+  - end_time
+  - repeat_every
+  - repeat_unit

src/components/schemas/common/ects.yaml

@@ -0,0 +1,3 @@
+description: The number of ECTS for this module
+type: number
+format: f32

src/components/schemas/common/mark.yaml

@@ -0,0 +1,3 @@
+type: number
+format: f32
+description: The (numerical) mark that was achieved

src/components/schemas/relations/course.yaml

@@ -0,0 +1,3 @@
+description: The governing course for this enrolment
+type: integer
+format: u32

src/components/schemas/relations/module.yaml

@@ -0,0 +1,3 @@
+type: integer
+format: u32
+description: Relation to a module

src/components/schemas/relations/term.yaml

@@ -0,0 +1,3 @@
+description: In which term this takes place
+type: integer
+format: u32

src/openapi.yaml

@@ -49,8 +49,8 @@ paths:
   # Me
   /me:
     $ref: ./paths/api/me/index.yaml
-  # /me/personal-events:
-  #   $ref: ./paths/api/me/personal-events.yaml
+  /me/personal-events:
+    $ref: ./paths/api/me/personal-events.yaml
   # /me/favourites:
   #   $ref: ./paths/api/me/favourites.yaml
   # /me/plans:

src/paths/api/me/personal-events.yaml

@@ -0,0 +1,18 @@
+get:
+  operationId: GetPersonalEvents
+  summary: >-
+    Get a list of personal events.
+
+    **THIS IS AN OPTIONAL ENDPOINT**: This endpoint might not be implemented, as it
+    requires a server running!
+  security: []
+  tags:
+    - Me
+    - Optional
+  responses:
+    "200":
+      $ref: ../../../components/responses/api/me/personal-events-get-200.yaml
+    "401":
+      $ref: ../../../components/responses/401.yaml
+    "404":
+      $ref: ../../../components/responses/404.yaml