Documents/proto/general/openapi.yaml

@@ -1,7 +1,9 @@
 openapi: 3.0.0
 info:
   title: ClydeAPI
-  description: Clyde's api
+  description:
+    This is the Clyde's api documentation. <br/>
+    Each endpoints are organised by endpoints **AND** by extensions making it easier to navigate.
   version: 0.0.1
 
 servers:
@@ -11,10 +13,10 @@ servers:
 paths:
   /ping:
     get:
-      summary: Vérifie l'état de l'api. 
+      summary: Check the API status 
       responses:
         default:
-          description: Retourne pong 
+          description: pong 
           content:
             text/plain:
               schema:
@@ -22,8 +24,9 @@ paths:
                 example: pong
   /users:
     get:
-      summary: Liste les utilisateurs
+      summary: list all users 
       tags:
+        - General
         - SI
       security:
         - bearer: []
@@ -48,9 +51,12 @@ paths:
   
   /user:
     get:
-      summary: Récupére ses informations 
+      summary: get informations about yourself 
       tags:
+        - General
         - Users
+      security:
+        - bearer: []
       responses:
         '200':
           description: Ok
@@ -58,9 +64,12 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/User"
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
     post:
-      summary: Créer un utilisateur
+      summary: Create user
       tags:
+        - General
         - Users
       requestBody:
         required: true
@@ -86,7 +95,7 @@ paths:
                 "FirstName": "John",
                 "Email": "John.Doe@example.com",
                 "Address": {
-                  "Address": "Rue de Tounais 42",
+                  "Address": "Rue de Tournais 42",
                   "Country": "BE"},
                 "BirthDate": "1941-02-22",
                 }
@@ -96,8 +105,9 @@ paths:
         '401':
           $ref: '#/components/responses/UnauthorizedError'
     patch:
-      summary: modifier ses informations
+      summary: Change informations about yourself 
       tags:
+        - General
         - Users
       security:
         - bearer: []
@@ -109,21 +119,10 @@ paths:
               $ref: '#/components/schemas/User'
       responses:
         '201':
-          description: Informations modifiées 
+          description: Successfully changed. 
         '401':
           $ref: '#/components/responses/UnauthorizedError'
   /user/{mat}:
-    get:
-      summary: Récupérer les informations d'un utilisateur
-      tags:
-        - Admin
-      responses:
-        '200':
-          description: Utilisateur trouvé
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/User"
     parameters:
       - name: mat
         in: path
@@ -131,9 +130,22 @@ paths:
         required: true
         schema:
           type: integer
-    patch:
+    get:
-      summary: modifier les informations d'un utilisateur
+      summary: Get user's informations 
       tags:
+        - General
+        - Admin
+      responses:
+        '200':
+          description: User found 
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+    patch:
+      summary: Alter user's informations 
+      tags:
+        - General
         - Admin
         - Secretariat
       security:
@@ -146,14 +158,14 @@ paths:
               $ref: '#/components/schemas/User'
       responses:
         '201':
-          description: Informations modifiées 
+          description: Successfully changed
         '401':
           $ref: '#/components/responses/UnauthorizedError'
-
   /course:
     post:
-      summary: Créer un nouveau cours
+      summary: Create new course 
       tags:
+        - General
         - Courses
         - Secretariat
       security: 
@@ -173,13 +185,14 @@ paths:
                     type: string
       responses:
         '201':
-          description: Nouveau cours crée
+          description: course created 
         '401':
           $ref: '#/components/responses/UnauthorizedError'
   /courses/{id}:
     get:
-      summary: Voir les informations sur un cours
+      summary: see courses informations 
       tags:
+        - General
         - Courses
       responses:
         '200':
@@ -195,8 +208,9 @@ paths:
         schema:
           type: integer
     delete:
-      summary: Suprimer un cours
+      summary: delete a course 
       tags:
+        - General
         - Courses
         - Secretariat
       security: 
@@ -207,8 +221,9 @@ paths:
         '401':
           $ref: '#/components/responses/UnauthorizedError'
     patch:
-      summary: Changer les options du cours
+      summary: Change course options 
       tags:
+        - General
         - Secretariat
         - Courses
       security:
@@ -242,14 +257,15 @@ paths:
                 }
       responses:
         '201':
-          description: Cours modifié 
+          description: Course modified
         '401':
           $ref: '#/components/responses/UnauthorizedError'
           
   /cursus:
     post:
-      summary: Créer un nouveau cursus
+      summary: Create a cursus
       tags:
+        - General
         - cursus
       security: 
         - bearer: []
@@ -262,33 +278,26 @@ paths:
               properties:
                 name:
                   type: string
-                credits:
+                courses: 
-                  type: integer
-                faculty:
-                  type: string
-                teachers:
-                  $ref: '#/components/schemas/User'
-                assistants:
                   type: array 
                   items:
-                    $ref: '#/components/schemas/User'
+                    type: integer
+                    description: id of courses
               example:
                 {
-                "name": "Math pour l'info",
+                "name": "Bac1",
-                "credits": 11,
+                []
-                "faculty": "science",
-                "Teacher": ,
-                "Assistants": [ ]
                 }
       responses:
         '201':
-          description: Nouveau cursus crée
+          description: Cursus created 
         '401':
           $ref: '#/components/responses/UnauthorizedError'
   /cursus/{id}:
     get:
-      summary: Voir les informations sur un cursus
+      summary: See Cursus's informations 
       tags:
+        - General
         - cursus
       responses:
         '200':
@@ -304,8 +313,9 @@ paths:
         schema:
           type: integer
     delete:
-      summary: Suprimer un cursus
+      summary: Delete cursus
       tags:
+        - General
         - cursus
       security: 
         - bearer: []
@@ -315,8 +325,9 @@ paths:
         '401':
           $ref: '#/components/responses/UnauthorizedError'
     patch:
-      summary: Changer les options du cursus
+      summary: Modify cursus 
       tags:
+        - General
         - cursus
       security:
         - bearer: []
@@ -349,7 +360,7 @@ paths:
                 }
       responses:
         '201':
-          description: Cours modifié 
+          description: Cursus modified 
         '401':
           $ref: '#/components/responses/UnauthorizedError'
           
@@ -503,7 +514,7 @@ components:
         "firstName": "John",
         "email": "John.Doe@example.com",
         "address": {
-          "address": "Rue de Tounais 42",
+          "address": "Rue de Tournais 42",
           "country": "BE"},
         "birthDate": "1941-02-22",
         "staffMember": true,
@@ -518,7 +529,7 @@ components:
           description: Follow the ISO-3166-1 alpha-2 standard.
       example:
         {
-          "address": "Rue de Tounais 42",
+          "address": "Rue de Tournais 42",
           "country": "BE"
         }
     Course:
@@ -533,18 +544,20 @@ components:
         faculty:
           type: string
         teachers:
-          $ref: '#/components/schemas/User'
+          type: integer 
+          description: user's id 
         assistants:
           type: array
           items:
-            $ref: '#/components/schemas/User'
+            type: integer
+            description: user's id
       example:
         {
         "id": 42,
         "name": "Math pour l'info",
         "credits": 11,
         "faculty": "science",
-        "Teacher": ,
+        "Teacher": 42,
         "Assistants": [ ]
         }
     Cursus:
@@ -606,5 +619,4 @@ components:
         
   responses:
     UnauthorizedError:
-      description: Permission non accordée
+      description: Unauthorized access or missing bearer 
-