From 38acfa6a4a78dee7a55b5154e3a59438b21497c7 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Fri, 7 Mar 2025 12:14:35 +0100
Subject: [PATCH] docs(backend): Assignments swagger annotaties

---
 .../entities/assignments/assignment.entity.ts |  35 ++++++
 .../src/entities/assignments/group.entity.ts  |  20 +++
 .../entities/assignments/submission.entity.ts |  33 +++++
 backend/src/routes/assignment.ts              | 119 +++++++++++++++++-
 4 files changed, 206 insertions(+), 1 deletion(-)

diff --git a/backend/src/entities/assignments/assignment.entity.ts b/backend/src/entities/assignments/assignment.entity.ts
index 89952c64..cfed653b 100644
--- a/backend/src/entities/assignments/assignment.entity.ts
+++ b/backend/src/entities/assignments/assignment.entity.ts
@@ -10,6 +10,41 @@ import { Class } from '../classes/class.entity.js';
 import { Group } from './group.entity.js';
 import { Language } from '../content/language.js';
 
+/**
+ * @swagger
+ * tags:
+ *   name: Assignment
+ *   description: Assignment management
+ * components:
+ *   schemas:
+ *     Assignment:
+ *       type: object
+ *       properties:
+ *         within:
+ *           $ref: '#/components/schemas/Class'
+ *         id:
+ *           type: number
+ *         title:
+ *           type: string
+ *         description:
+ *           type: string
+ *         learningPathHruid:
+ *           type: string
+ *         learningPathLanguage:
+ *           $ref: '#/components/schemas/Language'
+ *         groups:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/Group'
+ *       required:
+ *         - within
+ *         - id
+ *         - title
+ *         - description
+ *         - learningPathHruid
+ *         - learningPathLanguage
+ *         - groups
+ */
 @Entity()
 export class Assignment {
     @ManyToOne({
diff --git a/backend/src/entities/assignments/group.entity.ts b/backend/src/entities/assignments/group.entity.ts
index 5b224087..569f6f65 100644
--- a/backend/src/entities/assignments/group.entity.ts
+++ b/backend/src/entities/assignments/group.entity.ts
@@ -2,6 +2,26 @@ import { Entity, ManyToMany, ManyToOne, PrimaryKey } from '@mikro-orm/core';
 import { Assignment } from './assignment.entity.js';
 import { Student } from '../users/student.entity.js';
 
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     Group:
+ *       type: object
+ *       properties:
+ *         assignment:
+ *           $ref: '#/components/schemas/Assignment'
+ *         groupNumber:
+ *           type: number
+ *         members:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/Student'
+ *       required:
+ *         - assignment
+ *         - groupNumber
+ *         - members
+ */
 @Entity()
 export class Group {
     @ManyToOne({
diff --git a/backend/src/entities/assignments/submission.entity.ts b/backend/src/entities/assignments/submission.entity.ts
index 1bc28add..a94d37ad 100644
--- a/backend/src/entities/assignments/submission.entity.ts
+++ b/backend/src/entities/assignments/submission.entity.ts
@@ -3,6 +3,39 @@ import { Group } from './group.entity.js';
 import { Entity, Enum, ManyToOne, PrimaryKey, Property } from '@mikro-orm/core';
 import { Language } from '../content/language.js';
 
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     Submission:
+ *       type: object
+ *       properties:
+ *         learningObjectHruid:
+ *           type: string
+ *         learningObjectLanguage:
+ *           $ref: '#/components/schemas/Language'
+ *         learningObjectVersion:
+ *           type: string
+ *           default: '1'
+ *         submissionNumber:
+ *           type: number
+ *         submitter:
+ *           $ref: '#/components/schemas/Student'
+ *         submissionTime:
+ *           type: string
+ *           format: date-time
+ *         onBehalfOf:
+ *           $ref: '#/components/schemas/Group'
+ *         content:
+ *           type: string
+ *       required:
+ *         - learningObjectHruid
+ *         - learningObjectLanguage
+ *         - submissionNumber
+ *         - submitter
+ *         - submissionTime
+ *         - content
+ */
 @Entity()
 export class Submission {
     @PrimaryKey({ type: 'string' })
diff --git a/backend/src/routes/assignment.ts b/backend/src/routes/assignment.ts
index 4ae5756d..c747059c 100644
--- a/backend/src/routes/assignment.ts
+++ b/backend/src/routes/assignment.ts
@@ -1,13 +1,64 @@
+/**
+ * @swagger
+ * components:
+ *   parameters:
+ *     id:
+ *       in: path
+ *       name: id
+ *       schema:
+ *         type: string
+ *       description: The id of the assignment
+ *       required: true
+ *       example: 0
+ */
+
 import express from 'express';
 const router = express.Router();
 
-// Root endpoint used to search objects
+/**
+ * @swagger
+ * /assignment:
+ *   get:
+ *     summary: Get a list of assignments
+ *     tags: [Assignment]
+ *     parameters:
+ *     responses:
+ *       200:
+ *         description: A list of assignments
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 assignments:
+ *                   type: array
+ *                   items:
+ *                     type: string
+ *                     example: '0'
+ *                     description: The id of the assignment
+ */
 router.get('/', (req, res) => {
     res.json({
         assignments: ['0', '1'],
     });
 });
 
+/**
+ * @swagger
+ * /assignment/{id}:
+ *   get:
+ *     summary: Get an assignment by id
+ *     tags: [Assignment]
+ *     parameters:
+ *       - $ref: '#/components/parameters/id'
+ *     responses:
+ *       200:
+ *         description: An assignment
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Assignment'
+ */
 // Information about an assignment with id 'id'
 router.get('/:id', (req, res) => {
     res.json({
@@ -24,18 +75,84 @@ router.get('/:id', (req, res) => {
     });
 });
 
+/**
+ * @swagger
+ * /assignment/{id}/submissions:
+ *   get:
+ *     summary: Get a list of submissions for an assignment
+ *     tags: [Assignment]
+ *     parameters:
+ *       - $ref: '#/components/parameters/id'
+ *     responses:
+ *       200:
+ *         description: A list of submissions
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 submissions:
+ *                   type: array
+ *                   items:
+ *                     type: string
+ *                     example: '0'
+ */
 router.get('/:id/submissions', (req, res) => {
     res.json({
         submissions: ['0'],
     });
 });
 
+/**
+ * @swagger
+ * /assignment/{id}/groups:
+ *   get:
+ *     summary: Get a list of groups for an assignment
+ *     tags: [Assignment]
+ *     parameters:
+ *       - $ref: '#/components/parameters/id'
+ *     responses:
+ *       200:
+ *         description: A list of groups
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 groups:
+ *                   type: array
+ *                   items:
+ *                     type: string
+ *                     example: '0'
+ */
 router.get('/:id/groups', (req, res) => {
     res.json({
         groups: ['0'],
     });
 });
 
+/**
+ * @swagger
+ * /assignment/{id}/questions:
+ *   get:
+ *     summary: Get a list of questions for an assignment
+ *     tags: [Assignment]
+ *     parameters:
+ *       - $ref: '#/components/parameters/id'
+ *     responses:
+ *       200:
+ *         description: A list of questions
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 questions:
+ *                   type: array
+ *                   items:
+ *                     type: string
+ *                     example: '0'
+ */
 router.get('/:id/questions', (req, res) => {
     res.json({
         questions: ['0'],