feat: Add /me endpoint

Issue #10

README.md

@@ -1,3 +1,24 @@
 # Modulplaner OpenAPI
 
 OpenAPI documentation of the modulplaner API
+
+## Definitions
+
+- `Module`:  A specific unit or component of a broader course of study. It focuses on a
+  particular topic or subject area within a course. Modules are usually part of a larger
+  framework, and a course will consist of multiple modules.
+- `Course`: Refers to the entire program of study leading to a degree. It encompasses
+  multiple modules that are structured over the duration of the (bachelors) program.
+- `Term`: Refers to any academic period, but it is often associated with systems that divide the academic year into two or more periods.
+- `Lecture`: A single session, where the *lecture* of a *Module* is held.
+- `Lecture Series`: An entire series over a *term* of *lectures* (of a single class)
+- `Class`: A subset of students, that attend a *Lecture*.
+- `Lecturer`: The person teaching the students.
+- `Student`: The person, who should be learning about new stuff.
+
+
+### Do not use these terms
+
+- `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.

src/components/examples/401.yaml

@@ -0,0 +1 @@
+error: You are not authorized to access this endpoint

src/components/responses/401.yaml

@@ -0,0 +1,7 @@
+description: OK
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/error.yaml
+    example:
+      $ref: ../examples/401.yaml

src/components/responses/api/me/index-get-200.yaml

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

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

@@ -0,0 +1,58 @@
+type: object
+description: Enrolment status of a `Lecture Series`
+properties:
+  status:
+    description: If this enrolment is still active
+    type: string
+    oneOf:
+      - id: enrolled
+        const: enrolled
+        description: Currently enrolled, but the lectures have not yet started
+      - id: active
+        const: active
+        description: Enrolled and currently taking part
+      - id: completed
+        const: completed
+        description: Completed the
+      - id: cancelled
+        const: cancelled
+        description: The enrolment was cancelled
+      - id: failed
+        const: failed
+        description: The student failed the module
+  course_pk:
+    description: The governing course for this enrolment
+    type: number
+    format: i32
+  term_pk:
+    description: The term, in which this enrolment took place in
+    type: number
+    format: i32
+  ects:
+    description: The number of ECTS awarded
+    type: number
+    format: f32
+  mark:
+    description: The achieved mark
+    type: number
+    format: f32
+  module_pk:
+    description: The module, which the student enrolled in
+    type: number
+    format: i32
+  start_date:
+    description: When this enrolment started (UNIX timestamp in seconds)
+    type: number
+    format: i64
+  end_date:
+    description: When this enrolment ended (UNIX timestamp in seconds)
+    format: i64
+required:
+  - status
+  - course_pk
+  - term_pk
+  - ects
+  - mark
+  - module_pk
+  - start_date
+  - end_date

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

@@ -0,0 +1,20 @@
+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
+  ects:
+    type: number
+    format: f32
+    description: How many ects were awarded
+  mark:
+    type: number
+    format: f32
+    description: The (numerical) mark that was achieved
+required:
+  - module_pk
+  - ects
+  - mark

src/components/schemas/api/me.yaml

@@ -0,0 +1,41 @@
+type: object
+properties:
+  given_name:
+    type: string
+    description: Given/first name of the student
+  surname:
+    type: string
+    description: Surname of the student
+  cadastral_number:
+    type: integer
+    format: int64
+    description: Unique enrolment number for a student
+  credited_modules:
+    type: array
+    items:
+      $ref: ./me-module.yaml
+  gifted_credits:
+    type: array
+    items:
+      properties:
+        ects:
+          type: number
+          format: f32
+          description: The number of ECTS awarded
+        reason:
+          type: string
+          description: The reason for receiving the credits
+      required:
+        - ects
+        - reason
+  enrolments:
+    type: array
+    items:
+      $ref: ./me-enrolment.yaml
+required:
+  - given_name
+  - surname
+  - cadastral_number
+  - credited_modules
+  - gifted_credits
+  - enrolments

src/openapi.yaml

@@ -45,3 +45,13 @@ paths:
     $ref: ./paths/assets/changelog.yaml
   /assets/semesters/{semester}/version/{version}/file/{file}:
     $ref: ./paths/assets/semesters/{semester}/versions/{version}/file.yaml
+
+  # Me
+  /me:
+    $ref: ./paths/api/me/index.yaml
+  # /me/personal-events:
+  #   $ref: ./paths/api/me/personal-events.yaml
+  # /me/favourites:
+  #   $ref: ./paths/api/me/favourites.yaml
+  # /me/plans:
+  #   $ref: ./paths/api/me/plans.yaml

src/paths/api/me/index.yaml

@@ -0,0 +1,18 @@
+get:
+  operationId: GetMe
+  summary: >-
+    Get information about myself.
+
+    **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/index-get-200.yaml
+    "401":
+      $ref: ../../../components/responses/401.yaml
+    "404":
+      $ref: ../../../components/responses/404.yaml