[API] Add group creation and registration functionality (#1640)

* #1633

* Create model for groups (#1633)

* Add group controller (#1634)

* Add group service (#1634)

* Add migration for user group field (#1635)

* Add Controller for Group Registration (#1636)

* Add Service for Group Registration (#1636)

* Add MembershipExceedException (#1637)

* Correct lint errors (#1632)

* docs(core): update api docs with group routes

---------

Co-authored-by: Jonas Kuche <jonas-ian.kuche@mni.thm.de>

modules/fbs-core/api/api-docs.yml

@@ -19,6 +19,10 @@ tags:
     description: The Semester api
   - name: Course Registration
     description: The course registration api
+  - name: Group
+    description: The group API
+  - name: GroupMembership
+    description: The group Membership
   - name: Task
     description: The task api
   - name: Course evaluation
@@ -859,6 +863,287 @@ paths:
           description: Unauthorized
         "403":
           description: Forbidden
+  /courses/{cid}/groups:
+    get:
+      operationId: getGroups
+      tags:
+        - Group
+      summary: Get a group list
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+        - name: visible
+          in: query
+          required: false
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Group'
+        '403':
+          description: Forbidden
+    post:
+      operationId: createGroup
+      tags:
+        - Group
+      summary: Create a new group
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GroupRequest'
+      responses:
+        '200':
+          description: Group created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Group'
+        '400':
+          description: Bad Request
+        '403':
+          description: Forbidden
+  /courses/{cid}/groups/{gid}:
+    get:
+      operationId: getGroup
+      tags:
+        - Group
+      summary: Get a single group by id
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+        - name: gid
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Group'
+        '403':
+          description: Forbidden
+        '404':
+          description: Not Found
+    put:
+      operationId: updateGroup
+      tags:
+        - Group
+      summary: Update a single group by id
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+        - name: gid
+          in: path
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GroupRequest'
+      responses:
+        '204':
+          description: No Content
+        '400':
+          description: Bad Request
+        '403':
+          description: Forbidden
+    delete:
+      operationId: deleteGroup
+      tags:
+        - Group
+      summary: Delete a group by id
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+        - name: gid
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '204':
+          description: No Content
+        '403':
+          description: Forbidden
+  /courses/{cid}/groups/{gid}/users/{uid}:
+    put:
+      tags:
+        - GroupMembership
+      summary: Add a user to a group within a course
+      operationId: addUserToGroup
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Course ID
+        - name: gid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Group ID
+        - name: uid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: User ID
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '200':
+          description: User added to the group
+        '403':
+          description: Forbidden
+        '404':
+          description: Resource not found
+        '409':
+          description: Membership exceeded
+    delete:
+      tags:
+        - GroupMembership
+      summary: Remove a user from a group
+      operationId: removeUserFromGroup
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Course ID
+        - name: gid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Group ID
+        - name: uid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: User ID
+      responses:
+        '200':
+          description: User removed from the group
+        '403':
+          description: Forbidden
+  /courses/{cid}/groups/{gid}/users:
+    delete:
+      tags:
+        - GroupMembership
+      summary: Remove all users from a group
+      operationId: removeAllUsersFromGroup
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Course ID
+        - name: gid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Group ID
+      responses:
+        '200':
+          description: All users removed from the group
+        '403':
+          description: Forbidden
+  /users/{uid}/groups:
+    get:
+      tags:
+        - GroupMembership
+      summary: Retrieve all groups of a specific user
+      operationId: getUserGroups
+      parameters:
+        - name: uid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: User ID
+      responses:
+        '200':
+          description: List of groups
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Group'
+        '403':
+          description: Forbidden
+  /courses/{cid}/groups/{gid}/participants:
+    get:
+      tags:
+        - GroupMembership
+      summary: Get all course participants who are part of a group
+      operationId: getGroupParticipants
+      parameters:
+        - name: cid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Course ID
+        - name: gid
+          in: path
+          required: true
+          schema:
+            type: integer
+          description: Group ID
+      responses:
+        '200':
+          description: List of course participants
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+        '403':
+          description: Forbidden
   "/courses/{cid}/tasks":
     get:
       operationId: getCourseTasks
@@ -3197,10 +3482,9 @@ components:
       required: true
   securitySchemes:
     JWT:
-      type: apiKey
-      in: header
-      name: Authorization
-      description: Bearer
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
   schemas:
     User:
       type: object
@@ -3261,6 +3545,32 @@ components:
           type: integer
         name:
           type: string
+    Group:
+      type: object
+      properties:
+        id:
+          type: integer
+        cid:
+          type: integer
+        name:
+          type: string
+        membership:
+          type: integer
+        visible:
+          type: boolean
+    GroupRequest:
+      type: object
+      properties:
+        name:
+          type: string
+        membership:
+          type: integer
+        visible:
+          type: boolean
+      required:
+        - name
+        - membership
+        - visible
     Task:
       type: object
       required:

modules/fbs-core/api/src/main/resources/migrations/20_group_field_added.sql

@@ -0,0 +1,21 @@
+BEGIN;
+
+
+CREATE TABLE IF NOT EXISTS `fbs`.`group` (
+        `group_id` INT NOT NULL AUTO_INCREMENT, 
+        `course_id` INT NOT NULL,
+        `name` VARCHAR(100) NOT NULL,
+        `membership` INT NOT NULL,
+        `visible` TINYINT(1) NOT NULL DEFAULT 1,
+    PRIMARY KEY (`group_id`),
+    FOREIGN KEY (`course_id`) REFERENCES `fbs`.`course`(`course_id`),
+    UNIQUE INDEX `groups_groupid_courseid_uindex` (`group_id`, `course_id`))
+    ENGINE = InnoDB
+    DEFAULT CHARACTER SET = utf8mb4
+    COLLATE = utf8mb4_0900_ai_ci;
+
+INSERT INTO migration (number) VALUES (20);
+
+COMMIT;
+
+