Skip to content

Commit 7a27eb7

Browse files
RA341RA341
committed
fix docs
1 parent 431003b commit 7a27eb7

File tree

1 file changed

+145
-74
lines changed

1 file changed

+145
-74
lines changed

‎devU-api/src/entities/attendence/attendance.router.ts

Lines changed: 145 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@ import AttendanceController from './attendance.controller'
88
const Router = express.Router({ mergeParams: true })
99

1010
/**
11-
//
11+
* @swagger
1212
* tags:
13-
* name: Attendance
14-
* description: Attendance session management and submission
13+
* name: Attendance
14+
* description: Attendance session management and submission
1515
*/
1616

1717
/**
18-
// //
18+
* @swagger
1919
* components:
2020
* schemas:
2121
* AttendanceSessionResponse:
@@ -50,12 +50,9 @@ const Router = express.Router({ mergeParams: true })
5050
* AttendanceRequest:
5151
* type: object
5252
* required:
53-
* - courseId
5453
* - timeLimitSeconds
5554
* - maxTries
5655
* properties:
57-
* courseId:
58-
* type: integer
5956
* timeLimitSeconds:
6057
* type: integer
6158
* maxTries:
@@ -68,6 +65,7 @@ const Router = express.Router({ mergeParams: true })
6865
* attendanceCode:
6966
* type: string
7067
* description: The code submitted by the student.
68+
*
7169
* AttendanceSubmissionResponse:
7270
* type: object
7371
* properties:
@@ -77,13 +75,46 @@ const Router = express.Router({ mergeParams: true })
7775
* triesLeft:
7876
* type: integer
7977
* description: Number of attempts made (including this one). Placeholder - logic might differ.
78+
*
79+
* AttendanceSubmission:
80+
* type: object
81+
* properties:
82+
* id:
83+
* type: integer
84+
* description: Unique identifier for this submission record.
85+
* example: 543
86+
* sessionId:
87+
* type: integer
88+
* description: The ID of the attendance session this submission belongs to.
89+
* example: 101
90+
* success:
91+
* type: boolean
92+
* description: Whether this specific submission attempt was successful (code matched the session's code at the time).
93+
* example: true
94+
* submittedAt:
95+
* type: string
96+
* format: date-time
97+
* description: The exact time the submission was recorded by the system.
98+
* example: "2025-04-21T11:20:05.123Z" # Example timestamp
99+
* submission:
100+
* type: string
101+
* description: The actual code string submitted by the user.
102+
* example: "ABCD12"
103+
* required:
104+
* - id
105+
* - sessionId
106+
* - success
107+
* - submittedAt
108+
* - submission
80109
*/
81110

82111
/**
83-
//
112+
* @swagger
84113
* /attendance/course/{courseId}:
85114
* get:
86-
* summary: Retrieve all active attendance sessions for a specific course (Requires course editing privileges)
115+
* summary: Retrieve all active attendance sessions for a specific course
116+
* tags:
117+
* - Attendance
87118
* parameters:
88119
* - name: courseId
89120
* in: path
@@ -113,41 +144,75 @@ Router.get(
113144
AttendanceController.getSessionsByCourse,
114145
)
115146

116-
Router.get(
117-
'/:id/results',
118-
isAuthorized('courseEdit'),
119-
asInt('id'),
120-
AttendanceController.getAllSubmissions,
121-
)
122-
123-
124147
/**
125-
//
126-
* /attendance/{id}:
148+
* @swagger
149+
* /attendance/{id}/results:
127150
* get:
128-
* summary: Retrieve a specific attendance session by its ID (Requires course editing privileges)
151+
* summary: Retrieve all submissions for a specific attendance session
152+
* tags:
153+
* - Attendance
129154
* parameters:
130155
* - name: id
131156
* in: path
132157
* required: true
133-
* description: Unique ID of the attendance session
158+
* description: ID of the attendance session to retrieve results for
134159
* schema:
135160
* type: integer
136161
* responses:
137162
* '200':
138-
* description: Details of the attendance session.
163+
* description: A list of all submission records for the specified attendance session.
139164
* content:
140165
* application/json:
141166
* schema:
142-
* $ref: '#/components/schemas/AttendanceSessionResponse' # Use a serialized response schema
167+
* type: array
168+
* items:
169+
* $ref: '#/components/schemas/AttendanceSubmission'
143170
* '400':
144-
* description: Invalid ID supplied.
171+
* description: Invalid session ID supplied (e.g., not an integer).
145172
* '401':
146-
* description: Unauthorized.
173+
* description: Unauthorized (User is not logged in).
147174
* '403':
148175
* description: Forbidden (User lacks 'courseEdit' permission).
149176
* '404':
150-
* description: Attendance session not found.
177+
* description: Attendance session with the specified ID not found.
178+
* */
179+
Router.get(
180+
'/:id/results',
181+
isAuthorized('courseEdit'),
182+
asInt('id'),
183+
AttendanceController.getAllSubmissions,
184+
)
185+
186+
187+
/**
188+
@swagger
189+
* /attendance/{id}:
190+
* get:
191+
* summary: Retrieve a specific attendance session by its ID
192+
* tags:
193+
* - Attendance
194+
* parameters:
195+
* - name: id
196+
* in: path
197+
* required: true
198+
* description: Unique ID of the attendance session
199+
* schema:
200+
* type: integer
201+
* responses:
202+
* '200':
203+
* description: Details of the attendance session.
204+
* content:
205+
* application/json:
206+
* schema:
207+
* $ref: '#/components/schemas/AttendanceSessionResponse' # Use a serialized response schema
208+
* '400':
209+
* description: Invalid ID supplied.
210+
* '401':
211+
* description: Unauthorized.
212+
* '403':
213+
* description: Forbidden (User lacks 'courseEdit' permission).
214+
* '404':
215+
* description: Attendance session not found.
151216
*/
152217
Router.get(
153218
'/:id',
@@ -156,31 +221,33 @@ Router.get(
156221
AttendanceController.getSessionById,
157222
)
158223
/**
159-
//
224+
@swagger
160225
* /attendance:
161-
* post:
162-
* summary: Create a new attendance session (Requires course editing privileges)
163-
* requestBody:
164-
* required: true
165-
* content:
166-
* application/json:
167-
* schema:
168-
* $ref: '#/components/schemas/AttendanceRequest'
169-
* responses:
170-
* '201':
171-
* description: Attendance session created successfully.
172-
* content:
173-
* application/json:
174-
* schema:
175-
* $ref: '#/components/schemas/AttendanceSessionResponse'
176-
* '400':
177-
* description: Invalid request body or input data.
178-
* '401':
179-
* description: Unauthorized (Not logged in).
180-
* '403':
181-
* description: Forbidden (User lacks 'courseEdit' permission).
182-
* '500':
183-
* description: Server error during session creation.
226+
* post:
227+
* summary: Create a new attendance session
228+
* tags:
229+
* - Attendance
230+
* requestBody:
231+
* required: true
232+
* content:
233+
* application/json:
234+
* schema:
235+
* $ref: '#/components/schemas/AttendanceRequest'
236+
* responses:
237+
* '201':
238+
* description: Attendance session created successfully.
239+
* content:
240+
* application/json:
241+
* schema:
242+
* $ref: '#/components/schemas/AttendanceSessionResponse'
243+
* '400':
244+
* description: Invalid request body or input data.
245+
* '401':
246+
* description: Unauthorized (Not logged in).
247+
* '403':
248+
* description: Forbidden (User lacks 'courseEdit' permission).
249+
* '500':
250+
* description: Server error during session creation.
184251
*/
185252

186253
Router.post(
@@ -191,10 +258,12 @@ Router.post(
191258
)
192259

193260
/**
194-
//
261+
* @swagger
195262
* /attendance/{sessionId}/submit:
196263
* post:
197-
* summary: Submit an attendance code for a student (Requires permission to create self-submissions)
264+
* summary: Submit an attendance code for a student
265+
* tags:
266+
* - Attendance
198267
* parameters:
199268
* - name: sessionId
200269
* in: path
@@ -226,35 +295,37 @@ Router.post(
226295
* */
227296
Router.post(
228297
'/:sessionId/submit',
229-
isAuthorized('submissionCreateAll'),
298+
isAuthorized('submissionCreateSelf'),
230299
asInt('sessionId'),
231300
validateAttendanceSubmission,
232301
AttendanceController.submitAttendance,
233302
)
234303

235304
/**
236-
//
305+
@swagger
237306
* /attendance/{id}:
238-
* delete:
239-
* summary: Delete (soft delete) an attendance session (Requires course editing privileges)
240-
* parameters:
241-
* - name: id
242-
* in: path
243-
* required: true
244-
* description: ID of the attendance session to delete
245-
* schema:
246-
* type: integer
247-
* responses:
248-
* '204':
249-
* description: Session deleted successfully (No Content).
250-
* '400':
251-
* description: Invalid ID supplied.
252-
* '401':
253-
* description: Unauthorized.
254-
* '403':
255-
* description: Forbidden (User lacks 'courseEdit' permission).
256-
* '404':
257-
* description: Attendance session not found.
307+
* delete:
308+
* summary: Delete (soft delete) an attendance session
309+
* tags:
310+
* - Attendance
311+
* parameters:
312+
* - name: id
313+
* in: path
314+
* required: true
315+
* description: ID of the attendance session to delete
316+
* schema:
317+
* type: integer
318+
* responses:
319+
* '204':
320+
* description: Session deleted successfully (No Content).
321+
* '400':
322+
* description: Invalid ID supplied.
323+
* '401':
324+
* description: Unauthorized.
325+
* '403':
326+
* description: Forbidden (User lacks 'courseEdit' permission).
327+
* '404':
328+
* description: Attendance session not found.
258329
*/
259330
Router.delete(
260331
'/:id',

0 commit comments

Comments
 (0)