apispec.yaml

openapi: "3.0.3"

info:
  title: xyz class management
  description: class management tools for every school
  version: 1.0.0

servers:
  - url: http://localhost:8080/api

paths:
  /v1/users:
    get:
      tags:
        - users
      summary: get users only data information
      responses:
        "200":
          description: get users only data information success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/users"
        "500":
          $ref: "#/components/responses/500"
  /v1/users/register:
    post:
      tags:
        - users
      summary: create a new user
      requestBody:
        $ref: "#/components/requestBodies/insertUsers"
      responses:
        "200":
          description: create a new user success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 200
                  status:
                    type: string
                    example: "OK"
                  data:
                    $ref: "#components/schemas/insertUsers"
        "400":
          $ref: "#/components/responses/400"
        "500":
          $ref: "#/components/responses/500"
  /v1/users/login:
    post:
      tags:
        - users
      summary: user login
      requestBody:
        $ref: "#/components/requestBodies/insertUsers"
      responses:
        "200":
          description: login user success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 200
                  status:
                    type: string
                    example: "OK"
                  data:
                    $ref: "#components/schemas/insertUsers"
        "400":
          $ref: "#/components/responses/400"
        "500":
          $ref: "#/components/responses/500"
  /v1/users/{id}:
    get:
      tags:
        - users
      summary: get a user only data information
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: get a user only data success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/users"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    patch:
      summary: update a student information
      tags:
        - users
      parameters:
        - $ref: "#components/parameters/id"
      requestBody:
        $ref: "#/components/requestBodies/updateUsers"
      responses:
        "200":
          description: update a student information success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  status:
                    type: string
                  data:
                    $ref: "#components/schemas/updateUsers"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    delete:
      tags:
        - users
      summary: delete a user data only
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: delete a user data success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/delete"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"

  /v1/students/profile:
    get:
      tags:
        - students profile
      summary: get students information
      responses:
        "200":
          description: get all students information
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/students-profile"
                    minItems: 0
        "500":
          $ref: "#/components/responses/500"
  /v1/students/profile/{id}:
    get:
      tags:
        - students profile
      summary: get a student information
      parameters:
        - $ref: "#components/parameters/id"
      responses:
        "200":
          description: get a student information success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/students-profile"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
  /v1/students/:
    get:
      tags:
        - students
      summary: get students information
      responses:
        "200":
          description: get students information success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/users"
                minItems: 0
        "500":
          $ref: "#/components/responses/500"
  /v1/students/{id}:
    get:
      tags:
        - students
      summary: get a student only information
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: get students information success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/users"

        "500":
          $ref: "#/components/responses/500"

  /v1/instructors:
    get:
      tags:
        - instructors
      responses:
        "200":
          description: get students information success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/users"
                minItems: 0
        "500":
          $ref: "#/components/responses/500"
  /v1/instructors/{id}:
    get:
      tags:
        - instructors
      summary: get a student only information
      parameters:
        - $ref: "#/components/schemas/users"
      responses:
        "200":
          description: get students information success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/users"

        "500":
          $ref: "#/components/responses/500"

  /v1/classes:
    get:
      tags:
        - classes
      summary: get classes data
      responses:
        "200":
          description: get classes data success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/classes"
        "500":
          $ref: "#/components/responses/500"
    post:
      tags:
        - classes
      summary: add classes data
      requestBody:
        $ref: "#/components/requestBodies/insertOrUpdateClasses"
      responses:
        "200":
          description: add classes data success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/insertOrUpdateClasses"
        "400":
          $ref: "#/components/responses/400"
        "500":
          $ref: "#/components/responses/500"
  /v1/classes/{id}:
    get:
      summary: get a specific class
      tags:
        - classes
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: get a specific class success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/classes"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    patch:
      summary: update a class information
      tags:
        - classes
      parameters:
        - $ref: "#components/parameters/id"
      requestBody:
        $ref: "#/components/requestBodies/insertOrUpdateClasses"
      responses:
        "200":
          description: update a class information success
          content:
            application/json:
              schema:
                $ref: "#components/schemas/insertOrUpdateClasses"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    delete:
      tags:
        - classes
      summary: delete a class data only
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: delete a student data success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/delete"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"

  /v1/classes/{id}/students:
    post:
      tags:
        - class - students
      summary: add student(s) to a class
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        $ref: "#/components/requestBodies/insertClassStudents"
      responses:
        "200":
          description: add student(s) to a class
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/insertClassStudents"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    delete:
      tags:
        - class - students
      summary: delete student(s) in a class
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        $ref: "#/components/requestBodies/deleteClassStudents"
      responses:
        "200":
          description: delete student(s) success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/deleteClassStudents"

  /v1/classes/{id}/instructors:
    post:
      tags:
        - class - instructors
      summary: add student(s) to a class
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        $ref: "#/components/requestBodies/insertClassInstructors"
      responses:
        "200":
          description: add student(s) to a class
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/insertClassInstructors"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    delete:
      tags:
        - class - instructors
      summary: delete student(s) in a class
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        $ref: "#/components/requestBodies/deleteClassInstructors"
      responses:
        "200":
          description: delete student(s) success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/deleteClassInstructors"

components:
  schemas:
    classes:
      type: object
      properties:
        _id:
          type: string
          example: as8ohr43843n
        name:
          type: string
          example: mathematics
        room:
          type: string
          nullable: true
          example: online
        students:
          type: array
          items:
            $ref: "#/components/schemas/users"
        instructors:
          type: array
          items:
            $ref: "#/components/schemas/users"
          minimum: 0
        status:
          type: string
          enum:
            - scheduled
            - ongoing
            - completed
            - cancelled
          default: scheduled
          example: scheduled
        schedule:
          type: string
          format: date-time
        notes:
          type: string
          example: trial class for newcomers
          nullable: true
      minProperties: 2
      additionalProperties: false

    classes-only:
      type: object
      properties:
        _id:
          type: string
          example: as8ohr43843n
        name:
          type: string
          example: mathematics
        status:
          type: string
          enum:
            - scheduled
            - ongoing
            - completed
            - cancelled
          default: scheduled
          example: scheduled
        schedule:
          type: string
          format: date-time
        notes:
          type: string
          example: trial class for newcomers
          nullable: true
      minProperties: 2
      additionalProperties: false

    users:
      type: object
      properties:
        _id:
          type: string
          example: n2kohvj23kl
        email:
          type: string
          format: email
          example: Noora@noralo.com
        name:
          type: string
          example: "Noora"
        role:
          type: string
          enum:
            - instructor
            - student
          example: instructor
        # created_date:
        #   type: string
        #   format: date-time
        # updated_date:
        #   type: string
        #   format: date-time
      minProperties: 2
      maxProperties: 5
      additionalProperties: false
      required:
        - name
        - email

    students-profile:
      type: object
      properties:
        _id:
          type: string
          example: b12asdf23ksa3
        name:
          type: string
          example: "Joko"
        email:
          type: string
          example: Joko@joko.com
        classes:
          type: array
          items:
            $ref: "#/components/schemas/classes-only"
        # created_date:
        #   type: string
        #   format: date-time
        # updated_date:
        #   type: string
        #   format: date-time
      minProperties: 5
      maxProperties: 5
      additionalProperties: false

    errors:
      type: object
      properties:
        code:
          type: number
        status:
          type: string
        data:
          type: object
          properties:
            error:
              type: string

    insertUsers:
      type: object
      properties:
        email:
          type: string
          example: Joko@joko.com
        name:
          type: string
          example: "Joko"
        role:
          type: string
          example: student

    updateUsers:
      type: object
      properties:
        name:
          type: string
          example: "Joko"

    insertOrUpdateClasses:
      type: object
      properties:
        name:
          type: string
          example: mathematics
        room:
          type: number
          example: 1
        status:
          type: string
          enum:
            - scheduled
            - ongoing
            - completed
            - cancelled
          default: scheduled
          example: scheduled
        schedule:
          type: string
          format: date-time
        notes:
          type: string
          example: trial class for newcomers
          nullable: true

    insertClassStudents:
      type: object
      properties:
        students:
          type: array
          items:
            properties:
              studentId:
                type: string
              classId:
                type: string

      minItems: 1

    deleteClassStudents:
      type: object
      properties:
        students:
          type: object
          properties:
            studentId:
              type: array
              items:
                type: string
                example: n2kohvj23kl
            class_id:
              type: string
              example: as8ohr43843n
      minItems: 1

    insertClassInstructors:
      type: object
      properties:
        instructors:
          type: array
          items:
            properties:
              instructorId:
                type: string
              classId:
                type: string
      minItems: 1
      maxItems: 2

    deleteClassInstructors:
      type: object
      properties:
        instructors:
          type: object
          properties:
            studentId:
              type: array
              items:
                type: string
                example: n2kohvj23kl
              minItems: 1
            class_id:
              type: string
              example: as8ohr43843n
      minItems: 1

    delete:
      type: object
      properties:
        code:
          type: number
        status:
          type: string

  parameters:
    id:
      in: path
      name: id
      required: true
      schema:
        type: number
        minimum: 1
      description: id of specified resource

  requestBodies:
    insertUsers:
      description: Request body to insert and update users
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/insertUsers"
    updateUsers:
      description: Request body to insert and update users
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/updateUsers"
    insertOrUpdateClasses:
      description: Request body to insert or update classes
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/insertOrUpdateClasses"
    insertClassStudents:
      description: request body to insert students in a class
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/insertClassStudents"
    deleteClassStudents:
      description: request body to delete students in a class
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/deleteClassStudents"
    insertClassInstructors:
      description: request body to insert or delete instructors in a class
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/insertClassInstructors"
    deleteClassInstructors:
      description: request body to insert or delete instructors in a class
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/deleteClassInstructors"

  responses:
    "400":
      description: Wrong input from the client
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors"
          example:
            code: 400
            status: Bad Request
            data:
              error: column.ID validation error
    "401":
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors"
          example:
            code: 401
            status: Unauthorized
            data:
              error: No token provided
    "404":
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors"
          example:
            code: 404
            status: Not Found
            data:
              error: User ID x8934yhf is not found!
    "500":
      description: Unexpected Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors"
          example:
            code: 500
            status: Internal Server Error
            data:
              error: pg.Name is not integer!