updated

backend/app.py

@@ -14,8 +14,9 @@
 from routes.subject import subject_router
 from routes.teacher import teacher_router
 from routes.user import users_router
+from routes.tags.swagger_tags import tags_metadata
 
-app = FastAPI(docs_url="/api/docs")
+app = FastAPI(docs_url="/api/docs", openapi_tags=tags_metadata)
 
 # Koppel routes uit andere modules.
 app.include_router(login_router, prefix="/api")

backend/routes/group.py

@@ -5,11 +5,11 @@
 from domain.logic.group import add_student_to_group, remove_student_from_group
 from domain.models.StudentDataclass import StudentDataclass
 from routes.dependencies.role_dependencies import ensure_student_authorized_for_group
+from routes.tags.swagger_tags import Tags
 
 group_router = APIRouter()
 
-
-@group_router.post("/groups/{group_id}/join")
+@group_router.post("/groups/{group_id}/join", tags=[Tags.GROUP], summary="Join a certain group.")
 def group_join(
     group_id: int,
     student: StudentDataclass = Depends(ensure_student_authorized_for_group),
@@ -18,7 +18,7 @@ def group_join(
     add_student_to_group(session, student.id, group_id)
 
 
-@group_router.post("/groups/{group_id}/leave")
+@group_router.post("/groups/{group_id}/leave", tags=[Tags.GROUP], summary="Leave a certain group.")
 def group_leave(
     group_id: int,
     student: StudentDataclass = Depends(ensure_student_authorized_for_group),

backend/routes/login.py

@@ -7,12 +7,13 @@
 from domain.models.APIUser import LoginResponse
 from domain.models.UserDataclass import UserDataclass
 from routes.errors.authentication import InvalidAuthenticationError
+from routes.tags.swagger_tags import Tags
 
 # test url: https://login.ugent.be/login?service=https://localhost:8080/api/login
 login_router = APIRouter()
 
 
-@login_router.post("/login")
+@login_router.post("/login", tags=[Tags.LOGIN], summary="Starts a session for the user.")
 def login(
     ticket: str,
     session: Session = Depends(get_session),

backend/routes/project.py

@@ -10,11 +10,17 @@
     ensure_teacher_authorized_for_project,
     ensure_user_authorized_for_project,
 )
+from routes.tags.swagger_tags import Tags
 
 project_router = APIRouter()
 
 
-@project_router.get("/projects/{project_id}", dependencies=[Depends(ensure_user_authorized_for_project)])
+@project_router.get(
+    "/projects/{project_id}", 
+    dependencies=[Depends(ensure_user_authorized_for_project)], 
+    tags=[Tags.PROJECT],
+    summary="Get a certain project."
+)
 def project_get(
     project_id: int,
     session: Session = Depends(get_session),
@@ -23,15 +29,25 @@ def project_get(
     return project
 
 
-@project_router.get("/projects/{project_id}/groups", dependencies=[Depends(ensure_user_authorized_for_project)])
+@project_router.get(
+    "/projects/{project_id}/groups", 
+    dependencies=[Depends(ensure_user_authorized_for_project)], 
+    tags=[Tags.PROJECT],
+    summary="Get all formed groups of a certain project."
+)
 def project_get_groups(
     project_id: int,
     session: Session = Depends(get_session),
 ) -> list[GroupDataclass]:
     return get_groups_of_project(session, project_id)
 
 
-@project_router.post("/projects/{project_id}/groups", dependencies=[Depends(ensure_teacher_authorized_for_project)])
+@project_router.post(
+    "/projects/{project_id}/groups", 
+    dependencies=[Depends(ensure_teacher_authorized_for_project)], 
+    tags=[Tags.PROJECT],
+    summary="Create an empty group for a certain project."
+)
 def project_create_group(
     project_id: int,
     session: Session = Depends(get_session),

backend/routes/student.py

@@ -8,27 +8,28 @@
 from domain.models.StudentDataclass import StudentDataclass
 from domain.models.SubjectDataclass import SubjectDataclass
 from routes.dependencies.role_dependencies import get_authenticated_student
+from routes.tags.swagger_tags import Tags
 
 student_router = APIRouter()
 
 
-@student_router.get("/student/subjects")
+@student_router.get("/student/subjects", tags=[Tags.STUDENT], summary="Get all subjects of the student.")
 def subjects_of_student_get(
     session: Session = Depends(get_session),
     student: StudentDataclass = Depends(get_authenticated_student),
 ) -> list[SubjectDataclass]:
     return get_subjects_of_student(session, student.id)
 
 
-@student_router.get("/student/projects")
+@student_router.get("/student/projects", tags=[Tags.STUDENT], summary="Get all projects of the student.")
 def projects_of_student_get(
     session: Session = Depends(get_session),
     student: StudentDataclass = Depends(get_authenticated_student),
 ) -> list[ProjectDataclass]:
     return get_projects_of_student(session, student.id)
 
 
-@student_router.post("/student/subjects/{subject_id}/join")
+@student_router.post("/student/subjects/{subject_id}/join", tags=[Tags.STUDENT], summary="Join a certain subject (for student).")
 def student_subject_join(
     subject_id: int,
     session: Session = Depends(get_session),

backend/routes/subject.py

@@ -11,21 +11,22 @@
     ensure_user_authorized_for_subject,
     get_authenticated_user,
 )
+from routes.tags.swagger_tags import Tags
 
 subject_router = APIRouter()
 
 
-@subject_router.get("/subjects/{subject_id}", dependencies=[Depends(get_authenticated_user)])
+@subject_router.get("/subjects/{subject_id}", dependencies=[Depends(get_authenticated_user)], tags=[Tags.SUBJECT], summary="Get a certain subject.")
 def subject_get(subject_id: int, session: Session = Depends(get_session)) -> SubjectDataclass:
     return get_subject(session, subject_id)
 
 
-@subject_router.get("/subjects/{subject_id}/projects", dependencies=[Depends(ensure_user_authorized_for_subject)])
+@subject_router.get("/subjects/{subject_id}/projects", dependencies=[Depends(ensure_user_authorized_for_subject)], tags=[Tags.SUBJECT], summary="Get all projects of a certain subject.")
 def get_subject_projects(subject_id: int, session: Session = Depends(get_session)) -> list[ProjectDataclass]:
     return get_projects_of_subject(session, subject_id)
 
 
-@subject_router.post("/subjects/{subject_id}/projects", dependencies=[Depends(ensure_teacher_authorized_for_subject)])
+@subject_router.post("/subjects/{subject_id}/projects", dependencies=[Depends(ensure_teacher_authorized_for_subject)], tags=[Tags.SUBJECT], summary="Create a new project linked to a certain subject.")
 def new_project(
     subject_id: int,
     project: ProjectInput,

backend/routes/tags/swagger_tags.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+class Tags(Enum):
+    GROUP   = "Group methods"
+    LOGIN   = "Login methods"
+    PROJECT = "Project methods"
+    STUDENT = "Student methods"
+    SUBJECT = "Subject methods"
+    TEACHER = "Teacher methods"
+    USER    = "User methods"
+
+class _TagsDescription(Enum):
+    GROUP   = "All methods related to a group."
+    LOGIN   = "All methods related to logging in."
+    PROJECT = "All methods related to a project."
+    STUDENT = "All methods related to a student."
+    SUBJECT = "All methods related to a subject."
+    TEACHER = "All methods related to a teacher."
+    USER    = "All methods related to a user."
+
+tags_metadata = [{"name": tag, "description": _TagsDescription[tag.name]} for tag in Tags]

backend/routes/teacher.py

@@ -6,19 +6,20 @@
 from domain.models.SubjectDataclass import SubjectDataclass, SubjectInput
 from domain.models.TeacherDataclass import TeacherDataclass
 from routes.dependencies.role_dependencies import get_authenticated_teacher
+from routes.tags.swagger_tags import Tags
 
 teacher_router = APIRouter()
 
 
-@teacher_router.get("/teacher/subjects")
+@teacher_router.get("/teacher/subjects", tags=[Tags.TEACHER], summary="Get all subjects the teacher manages.")
 def subjects_of_teacher_get(
     session: Session = Depends(get_session),
     teacher: TeacherDataclass = Depends(get_authenticated_teacher),
 ) -> list[SubjectDataclass]:
     return get_subjects_of_teacher(session, teacher.id)
 
 
-@teacher_router.post("/teacher/subjects")
+@teacher_router.post("/teacher/subjects", tags=[Tags.TEACHER], summary="Create a new subject.")
 def create_subject_post(
     subject: SubjectInput,
     teacher: TeacherDataclass = Depends(get_authenticated_teacher),

backend/routes/user.py

@@ -9,19 +9,19 @@
 from domain.models.APIUser import APIUser
 from domain.models.UserDataclass import UserDataclass
 from routes.dependencies.role_dependencies import get_authenticated_admin, get_authenticated_user
+from routes.tags.swagger_tags import Tags
 
 users_router = APIRouter()
 
-
-@users_router.get("/user")
+@users_router.get("/user", tags=[Tags.USER], summary="Get the current user (and its roles).")
 def get_current_user(
     session: Session = Depends(get_session),
     uid: int = Depends(get_authenticated_user),
 ) -> APIUser:
     return convert_user(session, get_user(session, uid))
 
 
-@users_router.patch("/user")
+@users_router.patch("/user", tags=[Tags.USER], summary="Modify the language of the user.")
 def modify_current_user(
     language: str,
     session: Session = Depends(get_session),
@@ -31,19 +31,19 @@ def modify_current_user(
     return Response(status_code=status.HTTP_204_NO_CONTENT)
 
 
-@users_router.get("/users", dependencies=[Depends(get_authenticated_admin)])
+@users_router.get("/users", dependencies=[Depends(get_authenticated_admin)], tags=[Tags.USER], summary="Get all users.")
 def get_users(session: Session = Depends(get_session)) -> list[APIUser]:
     users: list[UserDataclass] = [user.to_domain_model() for user in get_all(session, User)]
     return [convert_user(session, user) for user in users]
 
 
-@users_router.get("/users/{uid}", dependencies=[Depends(get_authenticated_admin)])
+@users_router.get("/users/{uid}", dependencies=[Depends(get_authenticated_admin)], tags=[Tags.USER], summary="Get a certain user.")
 def admin_get_user(uid: int, session: Session = Depends(get_session)) -> APIUser:
     user: UserDataclass = get(session, User, uid).to_domain_model()
     return convert_user(session, user)
 
 
-@users_router.patch("/users/{uid}", dependencies=[Depends(get_authenticated_admin)])
+@users_router.patch("/users/{uid}", dependencies=[Depends(get_authenticated_admin)], tags=[Tags.USER], summary="Modify the roles of a certain user.")
 def modify_user(uid: int, roles: list[Role], session: Session = Depends(get_session)) -> Response:
     modify_user_roles(session, uid, roles)
     return Response(status_code=status.HTTP_204_NO_CONTENT)

frontend/.gitignore

@@ -22,3 +22,6 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+
+# React Component Preview
+previewConfig.json