feat: Everything has a PK

Close #14

src/components/enums/grading-type.yaml

@@ -1,12 +1,24 @@
 description: Types of grading
 type: string
 oneOf:
-  - title: HN
-    const: HN
-    description: TODO
-  - title: MSP
-    const: MSP
+  - title: Overall grade
+    const: overall_grade
+    description: An overall grade of the course
+  - title: Final exam
+    const: final_exam
     description: Final Exam
-  - title: SE
-    const: SE
-    description: TODO
+  - title: Midterm exams
+    const: midterm_exams
+    description: An exam, that is held in the middle of the term.
+  - title: Weekly exams
+    const: weekly_exams
+    description: An exam is held each week
+  - title: Report grading
+    const: report_grading
+    description: Reports are graded
+  - title: Homework grading
+    const: homework_grading
+    description: Homework is graded
+  - title: Presentation grading
+    const: presentation_grading
+    description: Presentations are graded

src/components/examples/api/lecturers/{lecturer}/index.yaml

@@ -0,0 +1,3 @@
+short: rabh
+surname: Racquel
+first_name: Bharath

src/components/examples/api/modules/index.yaml

@@ -1,37 +1,37 @@
-- short: aet1
+- pk: 1
+  short: aet1
   name: "Allgemeine Elektrotechnik 1 "
   courses:
-    - Elektro- und Informationstechnik
-    - Systemtechnik
-  module_pk: 6007771
+    - 1
+    - 2
+  internal_module_pk: 6007771
   module_related_pk:
-    - 6007771
+    - 6
   ects: 3
   marks:
-    - HN
-    - MSP
-    - SE
+    - overall_grade
+    - final_exam
+    - midterm_exams
   cat: Fachausbildung
   sub_cat: Fachgrundlagen
   dependencies:
     de:
-      - an1
+      - 5
     en: []
   enabling_modules:
     de:
-      - aet2
-      - msee
+      - 6
+      - 2
     en: []
-- short: ast1
+- pk: 2
+  short: ast1
   name: "Analoge Schaltungstechnik 1 "
-  courses: null
-  module_pk: null
-  module_related_pk: null
+  courses: []
+  internal_module_pk: null
+  module_related_pk: []
   ects: null
-  marks: null
+  marks: []
   cat: null
   sub_cat: null
   dependencies: {}
-  enabling_modules:
-    de: []
-    en: []
+  enabling_modules: {}

src/components/examples/api/modules/{module}/index.yaml

@@ -1,24 +1,25 @@
+pk: 3
 short: aet1
 name: "Allgemeine Elektrotechnik 1 "
 courses:
-  - Elektro- und Informationstechnik
-  - Systemtechnik
-module_pk: 6007771
+  - 1
+  - 2
+internal_module_pk: 6007771
 module_related_pk:
-  - 6007771
+  - 6007774
 ects: 3
 marks:
-  - HN
-  - MSP
-  - SE
+  - overall_grade
+  - final_exam
+  - midterm_exams
 cat: Fachausbildung
 sub_cat: Fachgrundlagen
 dependencies:
   de:
-    - an1
+    - 2
   en: []
 enabling_modules:
   de:
-    - aet2
-    - msee
+    - 4
+    - 5
   en: []

src/components/examples/api/terms/index.yaml

@@ -1,19 +1,6 @@
 - term: 24HS
   start_date: 1728175749
   end_date: 1728375749
-  revisions:
-    - einschr_3
-    - einschr_2
-    - einschr_1
 - term: 24FS
   start_date: 1728375750
   end_date: 1728575749
-  revisions:
-    - korr_2
-    - korr_2_1
-    - korr_1
-    - einschr_3_1
-    - einschr_3
-    - einschr_2
-    - einschr_1
-    - prov_4a

src/components/examples/api/terms/{term}/index.yaml

@@ -2,11 +2,27 @@ term: 24FS
 start_date: 1728175749
 end_date: 1728375749
 revisions:
-  - korr_2
-  - korr_2_1
-  - korr_1
-  - einschr_3_1
-  - einschr_3
-  - einschr_2
-  - einschr_1
-  - prov_4a
+  - pk: 1
+    name: korr_2
+    changes: HTML-Changelog
+  - pk: 2
+    name: korr_2_1
+    changes: HTML-Changelog
+  - pk: 3
+    name: korr_1
+    changes: HTML-Changelog
+  - pk: 4
+    name: einschr_3_1
+    changes: HTML-Changelog
+  - pk: 5
+    name: einschr_3
+    changes: HTML-Changelog
+  - pk: 6
+    name: einschr_2
+    changes: HTML-Changelog
+  - pk: 7
+    name: einschr_1
+    changes: HTML-Changelog
+  - pk: 8
+    name: prov_4a
+    changes: HTML-Changelog

src/components/parameters/course.yaml

@@ -3,6 +3,4 @@ in: path
 description: Course PK
 required: true
 schema:
-  type: integer
-  format: u32
-  summary: PK of the course to fetch
+  $ref: ../schemas/common/pk.yaml

src/components/parameters/lecturer.yaml

@@ -0,0 +1,6 @@
+name: lecturer
+in: path
+description: Lecturer
+required: true
+schema:
+  $ref: ../schemas/common/pk.yaml

src/components/parameters/module.yaml

@@ -3,5 +3,4 @@ in: path
 description: Module name
 required: true
 schema:
-  type: string
-  summary: Name of the module we want to get more specific information of.
+  $ref: ../schemas/common/pk.yaml

src/components/parameters/revision.yaml

@@ -3,8 +3,4 @@ in: path
 description: Term revision PK
 required: true
 schema:
-  type:
-    - string
-    - integer
-  format: u32
-  summary: PK of the revision to fetch. To fetch the latest revision, use `latest`
+  $ref: ../schemas/common/pk-latest.yaml

src/components/parameters/term.yaml

@@ -3,8 +3,4 @@ in: path
 description: Term
 required: true
 schema:
-  type:
-    - string
-    - integer
-  format: u32
-  summary: PK of the term to fetch. To fetch the latest term, use `latest`
+  $ref: ../schemas/common/pk-latest.yaml

src/components/responses/api/lecturers/{lecturer}/index-get-200.yaml

@@ -0,0 +1,7 @@
+description: OK
+content:
+  application/json:
+    schema:
+      $ref: ../../../../schemas/api/lecturer.yaml
+    example:
+      $ref: ../../../../examples/api/lecturers/{lecturer}/index.yaml

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

@@ -4,6 +4,6 @@ content:
     schema:
       type: array
       items:
-        $ref: ../../../schemas/api/term-revisions.yaml
+        $ref: ../../../schemas/api/term-revisions-overview.yaml
     example:
       $ref: ../../../examples/api/terms/index.yaml

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

@@ -1,9 +1,14 @@
 type: object
-description: The dependencies of a single module, split by language.
+description: |
+  The dependencies of a single module, split by language.
+
+  The language splitting can be important, as some module might be taught in multiple
+  languages. Sometimes, the dependencies change, based on the spoken language.
 additionalProperties:
   description: |
     The language (as the key), in which the module has a dependency to (array values).
+
+    Names according to ISO 639 (set 1), 2 character long codes.
   type: array
   items:
-    description: The short module name
-    type: string
+    $ref: ../relations/module.yaml

src/components/schemas/api/module.yaml

@@ -1,44 +1,48 @@
 type: object
 description: A single module definition
 properties:
+  pk:
+    $ref: ../common/pk.yaml
   short:
     description: Short name of the module / its human readable ID.
-    type: string
+    type:
+      - string
+      - "null"
+    default: null
   name:
     description: Full name of the module
     type: string
   courses:
-    description: List of courses, for which this module is meant.
-    type:
-      - array
-      - "null"
+    description: List of courses, for which this module belongs to.
+    type: array
+    default: []
     items:
-      type: string
-  module_pk:
-    description: The unique module ID number.
+      $ref: ../relations/course.yaml
+  internal_module_pk:
+    description: The internal unique module ID number of the university.
     type:
-      - number
+      - integer
       - "null"
+    default: null
+    format: u32
   module_related_pk:
-    description: TODO
-    type:
-      - array
-      - "null"
+    description: Related modules
+    type: array
+    default: []
     items:
-      type: integer
-      format: u32
+      $ref: ../relations/module.yaml
   ects:
     description: The number of ECTS this module awards upon completion.
     type:
       - number
       - "null"
+    default: null
   marks:
     description: |
       The types of marks that this module involves (Final exam, continuous grading,
       project, …).
-    type:
-      - array
-      - "null"
+    type: array
+    default: []
     items:
       $ref: ../../enums/grading-type.yaml
   cat:
@@ -46,6 +50,7 @@ properties:
     type:
       - string
       - "null"
+    default: null
   sub_cat:
     description: |
       Sub-category of the module (business administration, subject supplement,
@@ -53,23 +58,16 @@ properties:
     type:
       - string
       - "null"
+    default: null
   dependencies:
     description: |
       What dependencies are required to be able to participate in this module.
     $ref: ./module-dependency.yaml
+    default: {}
   enabling_modules:
     description: |
       List of modules, that can be attended, after the completion of this module.
     $ref: ./module-dependency.yaml
+    default: {}
 required:
   - short
-  - name
-  - courses
-  - module_pk
-  - module_related_pk
-  - ects
-  - marks
-  - cat
-  - sub_cat
-  - dependencies
-  - enabling_modules

src/components/schemas/api/term-revision.yaml

@@ -1,6 +1,8 @@
 type: object
 description: A single change in the term plan revision, outlining the changes
 properties:
+  pk:
+    $ref: ../common/pk.yaml
   name:
     description: The name of the revision
     type: string

src/components/schemas/api/term-revisions-overview.yaml

@@ -0,0 +1,21 @@
+type: object
+description: Single term and all of its revisions
+properties:
+  pk:
+    $ref: ../common/pk.yaml
+  term:
+    description: Name of the term
+    type: string
+    example: "24HS"
+  start_date:
+    description: Date, when the term starts
+    type: integer
+    format: u64
+  end_date:
+    description: Date, when the term ends
+    type: integer
+    format: u64
+required:
+  - term
+  - start_date
+  - end_date

src/components/schemas/api/term-revisions.yaml

@@ -1,6 +1,8 @@
 type: object
 description: Single term and all of its revisions
 properties:
+  pk:
+    $ref: ../common/pk.yaml
   term:
     description: Name of the term
     type: string
@@ -17,8 +19,9 @@ properties:
     description: The different revisions available for this term
     type: array
     items:
-      type: string
-      example: "einschr_1"
+      $ref: ./term-revision.yaml
 required:
   - term
+  - start_date
+  - end_date
   - revisions

src/components/schemas/common/pk-latest.yaml

@@ -0,0 +1,9 @@
+description: PK of the to fetch. To fetch the most up-to-date entry, use `latest`
+oneOf:
+  - type: integer
+    format: u32
+  - type: string
+    oneOf:
+      - id: latest
+        const: latest
+        description: The most up-to-date entry

src/openapi.yaml

@@ -24,6 +24,8 @@ paths:
   # Lecturers
   /api/lecturers:
     $ref: ./paths/api/lecturers/index.yaml
+  /api/lecturers/{lecturer}:
+    $ref: ./paths/api/lecturers/{lecturer}/index.yaml
 
   # Courses
   /api/courses:

src/paths/api/lecturers/{lecturer}/index.yaml

@@ -0,0 +1,12 @@
+get:
+  operationId: GetLecturer
+  summary: >-
+    Get a single lecturer
+  security: []
+  parameters:
+    - $ref: ../../../../components/parameters/lecturer.yaml
+  tags:
+    - Courses
+  responses:
+    "200":
+      $ref: ../../../../components/responses/api/lecturers/{lecturer}/index-get-200.yaml