From e9e0fdd9ecf05334fbaf39c4aa0c752dfe64e444 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C3=ABl=20Minelli?= <michael@minelli.me>
Date: Tue, 28 May 2024 02:20:57 +0200
Subject: [PATCH] OpenAPI => Add corrige routes documentation
---
ExpressAPI/assets/OpenAPI/OpenAPI.yaml | 183 ++++++++++++++++------
ExpressAPI/src/routes/AssignmentRoutes.ts | 13 +-
2 files changed, 145 insertions(+), 51 deletions(-)
diff --git a/ExpressAPI/assets/OpenAPI/OpenAPI.yaml b/ExpressAPI/assets/OpenAPI/OpenAPI.yaml
index 11ce447..8ebb216 100644
--- a/ExpressAPI/assets/OpenAPI/OpenAPI.yaml
+++ b/ExpressAPI/assets/OpenAPI/OpenAPI.yaml
@@ -73,17 +73,7 @@ paths:
- refreshToken
responses:
'200':
- description: OK
- content:
- application/json:
- schema:
- allOf:
- - $ref: '#/components/schemas/DojoBackendResponse'
- - type: object
- properties:
- data:
- type: object
- nullable: true
+ $ref: '#/components/responses/OK'
'404':
$ref: '#/components/responses/NOT_FOUND'
default:
@@ -306,17 +296,7 @@ paths:
- $ref: '#/components/parameters/assignmentNameOrUrl'
responses:
'200':
- description: OK
- content:
- application/json:
- schema:
- allOf:
- - $ref: '#/components/schemas/DojoBackendResponse'
- - type: object
- properties:
- data:
- type: object
- nullable: true
+ $ref: '#/components/responses/OK'
'401':
$ref: '#/components/responses/UNAUTHORIZED'
'404':
@@ -336,17 +316,93 @@ paths:
- $ref: '#/components/parameters/assignmentNameOrUrl'
responses:
'200':
- description: OK
- content:
- application/json:
- schema:
- allOf:
- - $ref: '#/components/schemas/DojoBackendResponse'
- - type: object
- properties:
- data:
- type: object
- nullable: true
+ $ref: '#/components/responses/OK'
+ '401':
+ $ref: '#/components/responses/UNAUTHORIZED'
+ '404':
+ $ref: '#/components/responses/NOT_FOUND'
+ default:
+ $ref: '#/components/responses/ERROR'
+ /assignments/{assignmentNameOrUrl}/corrections:
+ post:
+ tags:
+ - Assignment
+ summary: Link a exercise to an assignment as a correction
+ description: |
+ **🔒 Security needs:** TeachingStaff of the assignment or Admin role
+ security:
+ - Clients_Token: [ ]
+ parameters:
+ - $ref: '#/components/parameters/assignmentNameOrUrl'
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ allOf:
+ - type: object
+ properties:
+ exerciseIdOrUrl:
+ type: string
+ format: uuidv4
+ description: The id of the exercise to link
+ - $ref: '#/components/schemas/CorrectionsRequestBody'
+ required:
+ - exerciseIdOrUrl
+ responses:
+ '200':
+ $ref: '#/components/responses/OK'
+ '400':
+ $ref: '#/components/responses/BAD_REQUEST'
+ '401':
+ $ref: '#/components/responses/UNAUTHORIZED'
+ '404':
+ $ref: '#/components/responses/NOT_FOUND'
+ default:
+ $ref: '#/components/responses/ERROR'
+ /assignments/{assignmentNameOrUrl}/corrections/{exerciseIdOrUrl}:
+ patch:
+ tags:
+ - Assignment
+ summary: Update the correction link (f.e. commit SHA, description, etc.)
+ description: |
+ **🔒 Security needs:** TeachingStaff of the assignment or Admin role
+ security:
+ - Clients_Token: [ ]
+ parameters:
+ - $ref: '#/components/parameters/assignmentNameOrUrl'
+ - $ref: '#/components/parameters/exerciseIdOrUrl'
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ $ref: '#/components/schemas/CorrectionsRequestBody'
+ responses:
+ '200':
+ $ref: '#/components/responses/OK'
+ '400':
+ $ref: '#/components/responses/BAD_REQUEST'
+ '401':
+ $ref: '#/components/responses/UNAUTHORIZED'
+ '404':
+ $ref: '#/components/responses/NOT_FOUND'
+ default:
+ $ref: '#/components/responses/ERROR'
+ delete:
+ tags:
+ - Assignment
+ summary: Unlink a correction from an assignment
+ description: |
+ **🔒 Security needs:** TeachingStaff of the assignment or Admin role
+ security:
+ - Clients_Token: [ ]
+ parameters:
+ - $ref: '#/components/parameters/assignmentNameOrUrl'
+ - $ref: '#/components/parameters/exerciseIdOrUrl'
+ responses:
+ '200':
+ $ref: '#/components/responses/OK'
+ '400':
+ $ref: '#/components/responses/BAD_REQUEST'
'401':
$ref: '#/components/responses/UNAUTHORIZED'
'404':
@@ -415,7 +471,7 @@ paths:
$ref: '#/components/schemas/User'
default:
$ref: '#/components/responses/ERROR'
- /exercises/{exerciseId}/assignment:
+ /exercises/{exerciseIdOrUrl}/assignment:
get:
tags:
- Exercise
@@ -424,7 +480,7 @@ paths:
security:
- ExerciseChecker_Secret: [ ]
parameters:
- - $ref: '#/components/parameters/exerciseId'
+ - $ref: '#/components/parameters/exerciseIdOrUrl'
responses:
'200':
description: OK
@@ -456,7 +512,7 @@ paths:
$ref: '#/components/responses/NOT_FOUND'
default:
$ref: '#/components/responses/ERROR'
- /exercises/{exerciseId}/results:
+ /exercises/{exerciseIdOrUrl}/results:
post:
tags:
- Exercise
@@ -464,7 +520,7 @@ paths:
security:
- ExerciseChecker_Secret: [ ]
parameters:
- - $ref: '#/components/parameters/exerciseId'
+ - $ref: '#/components/parameters/exerciseIdOrUrl'
requestBody:
content:
multipart/form-data:
@@ -504,17 +560,7 @@ paths:
- archiveBase64
responses:
'200':
- description: OK
- content:
- application/json:
- schema:
- allOf:
- - $ref: '#/components/schemas/DojoBackendResponse'
- - type: object
- properties:
- data:
- type: object
- nullable: true
+ $ref: '#/components/responses/OK'
'401':
$ref: '#/components/responses/UNAUTHORIZED'
'404':
@@ -548,8 +594,8 @@ components:
required: true
schema:
type: string
- exerciseId:
- name: exerciseId
+ exerciseIdOrUrl:
+ name: exerciseIdOrUrl
description: The id of an exercise.
in: path
required: true
@@ -557,6 +603,19 @@ components:
type: string
format: uuidv4
schemas:
+ CorrectionsRequestBody:
+ type: object
+ properties:
+ description:
+ type: string
+ description: Short (max. 80 characters) description of the correction
+ commit:
+ type: string
+ format: Commit SHA
+ description: Long or short commit id (if not set, take the last commit)
+ externalDocs:
+ description: Commit SHA
+ url: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits
DojoBackendResponse:
type: object
properties:
@@ -848,6 +907,30 @@ components:
sessionToken: JWT token (for content, see schema named 'SessionTokenJWT')
data: null
responses:
+ OK:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/DojoBackendResponse'
+ example:
+ timestamp: '1992-09-30T19:00:00.000Z'
+ code: 200
+ description: OK
+ sessionToken: JWT token (for content, see schema named 'SessionTokenJWT')
+ data: null
+ BAD_REQUEST:
+ description: BAD_REQUEST
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/DojoBackendResponse'
+ example:
+ timestamp: '1992-09-30T19:00:00.000Z'
+ code: 400
+ description: BAD_REQUEST
+ sessionToken: JWT token (for content, see schema named 'SessionTokenJWT')
+ data: null
UNAUTHORIZED:
description: UNAUTHORIZED
content:
diff --git a/ExpressAPI/src/routes/AssignmentRoutes.ts b/ExpressAPI/src/routes/AssignmentRoutes.ts
index 583e6aa..5f46129 100644
--- a/ExpressAPI/src/routes/AssignmentRoutes.ts
+++ b/ExpressAPI/src/routes/AssignmentRoutes.ts
@@ -59,6 +59,17 @@ class AssignmentRoutes implements RoutesManager {
}
};
+ private readonly assignmentUpdateCorrigeValidator: ExpressValidator.Schema = {
+ commit : {
+ trim : true,
+ notEmpty: false
+ },
+ description: {
+ trim : true,
+ notEmpty: false
+ }
+ };
+
registerOnBackend(backend: Express) {
backend.get('/assignments/:assignmentNameOrUrl', SecurityMiddleware.check(true), this.getAssignment.bind(this) as RequestHandler);
backend.post('/assignments', SecurityMiddleware.check(true, SecurityCheckType.TEACHING_STAFF), ParamsValidatorMiddleware.validate(this.assignmentValidator), this.createAssignment.bind(this) as RequestHandler);
@@ -67,7 +78,7 @@ class AssignmentRoutes implements RoutesManager {
backend.patch('/assignments/:assignmentNameOrUrl/unpublish', SecurityMiddleware.check(true, SecurityCheckType.ASSIGNMENT_STAFF), this.changeAssignmentPublishedStatus(false).bind(this) as RequestHandler);
backend.post('/assignments/:assignmentNameOrUrl/corrections', SecurityMiddleware.check(true, SecurityCheckType.ASSIGNMENT_STAFF), ParamsValidatorMiddleware.validate(this.assignmentAddCorrigeValidator), this.linkUpdateAssignmentCorrection(false).bind(this) as RequestHandler);
- backend.patch('/assignments/:assignmentNameOrUrl/corrections/:exerciseIdOrUrl', SecurityMiddleware.check(true, SecurityCheckType.ASSIGNMENT_STAFF), this.linkUpdateAssignmentCorrection(true).bind(this) as RequestHandler);
+ backend.patch('/assignments/:assignmentNameOrUrl/corrections/:exerciseIdOrUrl', SecurityMiddleware.check(true, SecurityCheckType.ASSIGNMENT_STAFF), ParamsValidatorMiddleware.validate(this.assignmentUpdateCorrigeValidator), this.linkUpdateAssignmentCorrection(true).bind(this) as RequestHandler);
backend.delete('/assignments/:assignmentNameOrUrl/corrections/:exerciseIdOrUrl', SecurityMiddleware.check(true, SecurityCheckType.ASSIGNMENT_STAFF), this.unlinkAssignmentCorrection.bind(this) as RequestHandler);
}
--
GitLab