Update API documentation for courses endpoints

api/views/documentation/courses/course.yml

@@ -1,4 +1,4 @@
-Retrieves a course from the DB
+Course API
 ---
 tags:
   - Courses
@@ -7,45 +7,105 @@ parameters:
     in: path
     type: string
     required: true
-    description: The id of the course to retrieve
-responses:
-  404:
-    description: A course with the id does not exist
-  200:
-    description: "Request returned successfully"
-    schema:
+    description: The ID of the course to retrieve, update, or delete
+
+get:
+  summary: Retrieves a course from the DB
+  responses:
+    200:
+      description: "Request returned successfully"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Course'
+          example:
+            created_at: "2017-03-25T02:17:06"
+            department: "Agricultural Engineering"
+            department_id: "53af4926-52ee-41d0-9acc-ae7230300003"
+            id: "53af4926-52ee-41d0-9acc-ae7230500044"
+            level: 400
+            name: "Circuit-Techniques for Agricultural Engineering"
+            teacher: "MELVEN DARRAL"
+            teacher_id: "53af4926-52ee-41d0-9acc-ae7230400014"
+    404:
+      description: A course with the specified ID does not exist
+
+put:
+  summary: Updates an existing course
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/CourseUpdate'
+  responses:
+    200:
+      description: Course updated successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Course'
+    400:
+      description: Bad request (invalid JSON)
+    404:
+      description: Course with the specified ID does not exist
+
+delete:
+  summary: Deletes a course
+  responses:
+    200:
+      description: Course deleted successfully
+      content:
+        application/json:
+          schema:
+            type: object
+          example: {}
+    404:
+      description: Course with the specified ID does not exist
+
+components:
+  schemas:
+    Course:
       type: object
       properties:
         created_at:
           type: string
+          format: date-time
           description: Time of creation of the Course
+        department:
+          type: string
+          description: Course's department
+        department_id:
+          type: string
+          format: uuid
+          description: The UUID of the Course's department
         id:
           type: string
+          format: uuid
           description: The UUID of the Course
+        level:
+          type: integer
+          description: Course's level
         name:
           type: string
           description: Course's name
         teacher:
           type: string
-          description: Name of the course teacher
+          description: Course's teacher
         teacher_id:
           type: string
-          description: The UUID of the course teacher
+          format: uuid
+          description: The UUID of the Course's teacher
+    CourseUpdate:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Course's name
         level:
           type: integer
-          description: Course's academic level
-        department:
-          type: string
-          description: Department offering the course
-        department_id:
+          description: Course's level
+        teacher_id:
           type: string
-          description: The UUID of the department offering the course
-      example:
-        created_at: "2017-03-25T02:17:06"
-        department: "Agricultural Engineering"
-        department_id: "53af4926-52ee-41d0-9acc-ae7230300003"
-        id: "53af4926-52ee-41d0-9acc-ae7230500044"
-        level: 400
-        name: "Circuit-Techniques for Agricultural Engineering"
-        teacher: "MELVEN DARRAL"
-        teacher_id: "53af4926-52ee-41d0-9acc-ae7230400014"
+          format: uuid
+          description: The UUID of the Course's teacher

api/views/documentation/courses/course_teacher.yml

@@ -1,48 +1,56 @@
-Retrieves the teacher of a specific course
+Course Teacher API
 ---
 tags:
   - Courses
 parameters:
   - name: course_id
     in: path
-    description: The ID of the course
+    type: string
     required: true
-    schema:
-      type: string
-responses:
-  200:
-    description: "Request returned successfully"
-    content:
-      application/json:
-        schema:
-          type: object
-          properties:
-            created_at:
-              type: string
-              description: Time of creation of the Teacher
-            department_id:
-              type: string
-              description: The UUID of the Teacher's department
-            email:
-              type: string
-              description: Teacher's email
-            first_name:
-              type: string
-              description: Teacher's first name
-            id:
-              type: string
-              description: The UUID of the Teacher
-            last_name:
-              type: string
-              description: Teacher's last name
-            recovery_question:
-              type: string
-              description: Teacher's password recovery question
-        example:
-          created_at: "2017-03-25T02:17:06"
-          department_id: "53af4926-52ee-41d0-9acc-ae7230300003"
-          email: "[email protected]"
-          first_name: "MELVEN"
-          id: "53af4926-52ee-41d0-9acc-ae7230400014"
-          last_name: "DARRAL"
-          recovery_question: "What is the name of your childhood best friend?"
+    description: The ID of the course to retrieve the teacher for
+
+get:
+  summary: Retrieves the teacher of a specific course
+  responses:
+    200:
+      description: "Request returned successfully"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Teacher'
+          example:
+            created_at: "2017-03-25T02:17:06"
+            email: "[email protected]"
+            first_name: "MELVEN"
+            id: "53af4926-52ee-41d0-9acc-ae7230400014"
+            last_name: "DARRAL"
+            recovery_question: "What is your favorite book?"
+    404:
+      description: Course with the specified ID does not exist
+
+components:
+  schemas:
+    Teacher:
+      type: object
+      properties:
+        created_at:
+          type: string
+          format: date-time
+          description: Time of creation of the Teacher record
+        email:
+          type: string
+          format: email
+          description: Teacher's email address
+        first_name:
+          type: string
+          description: Teacher's first name
+        id:
+          type: string
+          format: uuid
+          description: The UUID of the Teacher
+        last_name:
+          type: string
+          description: Teacher's last name
+        recovery_question:
+          type: string
+          description: Teacher's password recovery question

api/views/documentation/courses/courses.yml

@@ -1,53 +1,111 @@
-Retrieves all courses from the DB
+Courses API
 ---
 tags:
   - Courses
-responses:
-  200:
-    description: "Request returned successfully"
-    schema:
-      type: array
-      items:
-        type: object
-        properties:
-          created_at:
-            type: string
-            description: time of creation of the Course
-          department:
-            type: string
-            description: Course's department
-          department_id:
-            type: string
-            description: The uuid of the Course's department
-          id:
-            type: string
-            description: The uuid of the Course
-          level:
-            type: integer
-            description: Course's level
-          name:
-            type: string
-            description: Course's name
-          teacher:
-            type: string
-            description: Course's teacher
-          teacher_id:
-            type: string
-            description: The uuid of the Course's teacher
-      example:
-        - created_at: "2017-03-25T02:17:06"
-          department: "Agricultural Engineering"
-          department_id: "53af4926-52ee-41d0-9acc-ae7230300003"
-          id: "53af4926-52ee-41d0-9acc-ae7230500031"
-          level: 100
-          name: "Math for Agricultural Engineering"
-          teacher: "JEMMIE IRVINE"
-          teacher_id: "53af4926-52ee-41d0-9acc-ae7230400011"
-        - created_at: "2017-03-25T02:17:06"
-          department: "Agricultural Engineering"
-          department_id: "53af4926-52ee-41d0-9acc-ae7230300003"
-          id: "53af4926-52ee-41d0-9acc-ae7230500032"
-          level: 100
-          name: "Eng for Agricultural Engineering"
-          teacher: "MAZI AADIL"
-          teacher_id: "53af4926-52ee-41d0-9acc-ae7230400012"
+get:
+  summary: Retrieves all courses from the DB
+  parameters:
+    - name: level
+      in: query
+      type: integer
+      description: Filter courses by level
+  responses:
+    200:
+      description: "Request returned successfully"
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/Course'
+          example:
+            - created_at: "2017-03-25T02:17:06"
+              department: "Agricultural Engineering"
+              department_id: "53af4926-52ee-41d0-9acc-ae7230300003"
+              id: "53af4926-52ee-41d0-9acc-ae7230500031"
+              level: 100
+              name: "Math for Agricultural Engineering"
+              teacher: "JEMMIE IRVINE"
+              teacher_id: "53af4926-52ee-41d0-9acc-ae7230400011"
+            - created_at: "2017-03-25T02:17:06"
+              department: "Agricultural Engineering"
+              department_id: "53af4926-52ee-41d0-9acc-ae7230300003"
+              id: "53af4926-52ee-41d0-9acc-ae7230500032"
+              level: 100
+              name: "Eng for Agricultural Engineering"
+              teacher: "MAZI AADIL"
+              teacher_id: "53af4926-52ee-41d0-9acc-ae7230400012"
+
+post:
+  summary: Creates a new course
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/CourseCreate'
+  responses:
+    201:
+      description: Course created successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Course'
+    400:
+      description: Bad request (missing required fields or invalid JSON)
+
+components:
+  schemas:
+    Course:
+      type: object
+      properties:
+        created_at:
+          type: string
+          format: date-time
+          description: Time of creation of the Course
+        department:
+          type: string
+          description: Course's department
+        department_id:
+          type: string
+          format: uuid
+          description: The UUID of the Course's department
+        id:
+          type: string
+          format: uuid
+          description: The UUID of the Course
+        level:
+          type: integer
+          description: Course's level
+        name:
+          type: string
+          description: Course's name
+        teacher:
+          type: string
+          description: Course's teacher
+        teacher_id:
+          type: string
+          format: uuid
+          description: The UUID of the Course's teacher
+    CourseCreate:
+      type: object
+      required:
+        - name
+        - level
+        - teacher_id
+        - department_id
+      properties:
+        name:
+          type: string
+          description: Course's name
+        level:
+          type: integer
+          description: Course's level
+        teacher_id:
+          type: string
+          format: uuid
+          description: The UUID of the Course's teacher
+        department_id:
+          type: string
+          format: uuid
+          description: The UUID of the Course's department