Merge pull request 'openapi-dev' (#3) from openapi-dev into master

Reviewed-on: PGL/Clyde#3
Je suis ok les bg

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,39 +13,116 @@ servers:
 paths:
   /ping:
     get:
-      summary: Test if the api is up.
+      summary: Check the API status 
       responses:
         default:
-          description: Standard response to ping
+          description: pong 
           content:
             text/plain:
               schema:
                 type: string
                 example: pong
-  /user:
+  /users:
-    put:
+    get:
-      summary: create a new user
+      summary: list all users 
       tags:
-        - users
+        - General
+        - SI
+      security:
+        - bearer: []
+      parameters:
+        - in: query
+          name: type
+          required: false 
+          schema:
+            type: string
+            enum: [teacher, student, secretary]
+      responses: 
+        '200':
+          description: OK
+          content: 
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/User"
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+  
+  /user:
+    get:
+      summary: get informations about yourself 
+      tags:
+        - General
+        - Users
       security:
         - bearer: []
       responses:
         '200':
-          description: User created
+          description: Ok
-        '401':
-          $ref: '#/components/responses/UnauthorizedError'
-  /user/{mat}:
-    get:
-      summary: get user's info
-      tags:
-        - users
-      responses:
-        '200':
-          description: User found 
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/User"
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+    post:
+      summary: Create user
+      tags:
+        - General
+        - Users
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object 
+              properties:
+                LastName: 
+                  type: string
+                FirstName:
+                  type: string
+                Email:
+                  type: string
+                Address:
+                  $ref: "#/components/schemas/Address"
+                BirthDate:
+                  type: string
+                  description: Follow the iso 8601 ("YYYY-MM-DD")
+              example:
+                {
+                "LastName": "Doe" ,
+                "FirstName": "John",
+                "Email": "John.Doe@example.com",
+                "Address": {
+                  "Address": "Rue de Tournais 42",
+                  "Country": "BE"},
+                "BirthDate": "1941-02-22",
+                }
+      responses:
+        '201':
+          description: User created
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+    patch:
+      summary: Change informations about yourself 
+      tags:
+        - General
+        - Users
+      security:
+        - bearer: []
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/User'
+      responses:
+        '201':
+          description: Successfully changed. 
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+  /user/{mat}:
     parameters:
       - name: mat
         in: path
@@ -51,42 +130,241 @@ paths:
         required: true
         schema:
           type: integer
-
-  /cursus/{id}:
     get:
-      summary: Voir les informations sur un Cursus
+      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
+      security:
+        - bearer: []
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/User'
+      responses:
+        '201':
+          description: Successfully changed
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+  /course:
+    post:
+      summary: Create new course 
+      tags:
+        - General
+        - Courses
+        - Secretariat
+      security: 
+        - bearer: []
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                courses:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '201':
+          description: course created 
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+  /courses/{id}:
+    get:
+      summary: see courses informations 
+      tags:
+        - General
         - Courses
       responses:
         '200':
-          description: Cursus found
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Course'
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: integer
+    delete:
+      summary: delete a course 
+      tags:
+        - General
+        - Courses
+        - Secretariat
+      security: 
+        - bearer: []
+      responses:
+        '201':
+          description: Success
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+    patch:
+      summary: Change course options 
+      tags:
+        - General
+        - Secretariat
+        - Courses
+      security:
+        - bearer: []
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                credits:
+                  type: integer
+                faculty:
+                  type: string
+                teachers:
+                  type: object
+                  $ref: '#/components/schemas/User'
+                assistants:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/User'
+              example:
+                {
+                "name": "Math pour l'info",
+                "credits": 11,
+                "faculty": "science",
+                "Teacher": ,
+                "Assistants": [ ]
+                }
+      responses:
+        '201':
+          description: Course modified
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+          
+  /cursus:
+    post:
+      summary: Create a cursus
+      tags:
+        - General
+        - cursus
+      security: 
+        - bearer: []
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                courses: 
+                  type: array 
+                  items:
+                    type: integer
+                    description: id of courses
+              example:
+                {
+                "name": "Bac1",
+                []
+                }
+      responses:
+        '201':
+          description: Cursus created 
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+  /cursus/{id}:
+    get:
+      summary: See Cursus's informations 
+      tags:
+        - General
+        - cursus
+      responses:
+        '200':
+          description: OK
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Cursus'
-  /courses/{id}:
+    parameters:
-    get:
+      - name: id
-      summary: Voir les informations sur un cours*
+        in: path
-      tags:
+        required: true
-        - Courses
+        schema:
-      responses:
+          type: integer
-    
-    put:
-      summary: Créer un nouveau cours
-      tags:
-        - Courses
-      security: 
-        - bearer: []
-      responses:
-
     delete:
-      summary: Suprimer un cours
+      summary: Delete cursus
       tags:
-        - Courses
+        - General
+        - cursus
       security: 
         - bearer: []
       responses:
-
+        '201':
+          description: Success
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+    patch:
+      summary: Modify cursus 
+      tags:
+        - General
+        - cursus
+      security:
+        - bearer: []
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                credits:
+                  type: integer
+                faculty:
+                  type: string
+                teachers:
+                  type: object
+                  $ref: '#/components/schemas/User'
+                assistants:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/User'
+              example:
+                {
+                "name": "Math pour l'info",
+                "credits": 11,
+                "faculty": "science",
+                "Teacher": ,
+                "Assistants": [ ]
+                }
+      responses:
+        '201':
+          description: Cursus modified 
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+          
     
 components:
   securitySchemes:
@@ -97,54 +375,82 @@ components:
     User:
       type: object 
       properties:
-        RegNo:
+        regNo:
           type: integer
-        Photo:
+        photo:
           type: object
-        LastName: 
+        lastName: 
           type: string
-        FirstName:
+        firstName:
           type: string
-        Email:
+        email:
           type: string
-        Address:
+        address:
           $ref: "#/components/schemas/Address"
-        BirthDate:
+        birthDate:
           type: string
           description: Follow the iso 8601 ("YYYY-MM-DD")
-        StaffMember:
-          type: boolean
       example:
         {
-        "RegNo": 42,
+        "regNo": 42,
-        "LastName": "Doe" ,
+        "lastName": "Doe" ,
-        "FirstName": "John",
+        "firstName": "John",
-        "Email": "John.Doe@example.com",
+        "email": "John.Doe@example.com",
-        "Address": {
+        "address": {
-          "Address": "Rue de Tounais 42",
+          "address": "Rue de Tournais 42",
-          "Country": "BE"},
+          "country": "BE"},
-        "BirthDate": "1941-02-22",
+        "birthDate": "1941-02-22",
-        "StaffMember": true
+        "staffMember": true,
         }
     Address:
       type: object
       properties:
-        Address:
+        address:
           type: string
-        Country:
+        country:
           type: string
           description: Follow the ISO-3166-1 alpha-2 standard.
       example:
         {
-          "Address": "Rue de Tounais 42",
+          "address": "Rue de Tournais 42",
-          "Country": "BE"
+          "country": "BE"
+        }
+    Course:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        credits:
+          type: integer
+        faculty:
+          type: string
+        teachers:
+          type: integer 
+          description: user's id 
+        assistants:
+          type: array
+          items:
+            type: integer
+            description: user's id
+      example:
+        {
+        "id": 42,
+        "name": "Math pour l'info",
+        "credits": 11,
+        "faculty": "science",
+        "Teacher": 42,
+        "Assistants": [ ]
         }
     Cursus:
       type: object
       properties:
-        Id:
+        id:
           type: integer
-        Courses:
+        name:
+          type: string
+        courses:
           type: array
           items:
             type: string
@@ -155,4 +461,4 @@ components:
         }
   responses:
     UnauthorizedError:
-      description: Access token is missing or invalid
+      description: Unauthorized access or missing bearer