swagger.yaml

swagger: "2.0"
info:
  description: "This is the api-doc for general shit site's backend"
  version: "1.0.0"
  title: "GS backend"
servers:
  - url: "http://localhost:3000/"
    description: "development server"
tags:
- name: "Question Admin"
  description: ""
- name: "Super User"
  description: ""
- name: "User"
  description: "Operations about user"
- name: "Question"
  description: "Question and testcases endpoint"
- name: "Scoreboard"
  description: "scoreboard of all students"

schemes:
# - "https"
- "http"
paths:
  /superarea/login:
    post:
      tags:
      - "Super User"
      summary: "login with super user informaton"
      description: ""
      operationId: "addSuper"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "super user"
        required: true
        schema:
          $ref: "#/definitions/SuperUser"
      responses:
        "200":
          description: "superuser logged successfully"
          schema:
            type: "object"
            example:
             admin:
              username: "superuser username"
             token: "generated token"
        "400":
          description: "Error while validating"

  /superarea/logout:
    post:
      tags:
      - "Super User"
      summary: "super user will be logged out"
      description: "super user should be authenticated to request for logout"
      operationId: "superLogout"
      produces:
      - "application/json"
      parameters:
      - name: "Authorization"
        in: "header"
        description: "needs to be send in bearer thingy"
        required: true
        type: "string"
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            example:
                message: "successfully logged out"
              
        "500":
          description: "internal server error"

  /questionadmin/:
    post:
      tags:
      - "Question Admin"
      summary: "creates new question admin"

      operationId: "addQAdmin"
      produces:
      - "application/json"
      parameters:
      - name: "body"
        in: "body"
        required: true
        schema:
          type: "object"
          example:
            username: "question admins username"
            password: "question admin's password"
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"
        description: "only superuser can create new admins"
      responses:
        "201":
          description: "successful operation"
          schema:
            type: "object"
            example:
              questionAdmin:
                _id: "question admin's id"
                username : "newAdminUsername"
              message: "question admin created successfully"
        "400":
          description: "error message will be displayed"
    get:
      tags:
      - "Question Admin"
      summary: "returns all admins"
      operationId: "getAdmins"
      produces:
      - "application/json"
      parameters:
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"
      responses:
        "200":
          description: "returns all admins"
          schema:
            type: "object"
            example:
              -
                _id: "question admin's id"
                username : "newAdminUsername"

  /questionadmin/{username}:
    get:
      tags:
      - "Question Admin"
      summary: "get question admin by username"
      description: "Returns a specified question admin"
      operationId: "getadminByUsername"
      produces:
      - "application/json"
      parameters:
      - name: "username"
        in: "path"
        description: "username of admin to return"
        required: true
        type: "string"
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"
        
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            example:
                _id: "question admin's id"
                username : "newAdminUsername"
        "500":
          description: "error message will be returned"
      # security:
      # - api_key: []
    patch:
      tags:
      - "Question Admin"
      summary: "Updates a pet in the store with form data"
      description: ""
      operationId: "updatePetWithForm"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "body"
        in: "body"
        description: "updated info of question admin"
        required: false
        schema:
          type: "object"
          example:
            username: "updated username"
            password: "updated password"
      - name: "username"
        in: "path"
        required: true
        type: "string"
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"
      responses:
        "200":
          description: "returns good message or sth"
          schema:
            type: "object"
            example:
              message: "question admin updated successfully"
        "500":
          description: "error message will be returned"

    delete:
      tags:
      - "Question Admin"
      summary: "Deletes a question admin"
      description: ""
      operationId: "deleteAdmin"
      produces:
      - "application/json"
      parameters:
      - name: "username"
        in: "path"
        required: true
        type: "string"
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"

      responses:
        "200":
          description: "successfully removed"
          schema:
            type: "object"
            example: 
              questionAdmin :
                _id: "id of question admin"
                username: "the username of question admin"
              message : "admin successfully deleted"
          
        "500":
          description: "error message will be returned"

  /questionadmin/login:
    post:
      tags:
      - "Question Admin"
      summary: "logs question admin in"
      description: ""
      operationId: "qadminlogin"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "body"
        in: "body"
        description: "info of the question admin"
        required: true
        schema:
          type: "object"
          example:
            username: "qadmin username"
            password: "qadmin password"
      responses:
        "200":
          description: "logged in successfully"
          schema:
            type: "object"
            example :
             questionAdmin:
              _id: "id of question admin"
              username: "admin username"
             token: "token"
        "400":
          description: "error will be returned"
  /questionadmin/me/logout:
    post:
      tags:
      - "Question Admin"
      summary: "logs out the admin"
      description: "Returns a map of status codes to quantities"
      operationId: "adminLogout"
      produces:
      - "application/json"
      parameters: 
        - name: "Authorization"
          in: "header"
          required: true
          type: "string"
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            example:
              message: "logged out successfully"
        "500":
          description: "error will be returned"


  /user/:
    get:
      tags:
      - "User"
      summary: "gets all users"
      description: "This can only be done by superuser."
      operationId: "getAllUser"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "Authorization"
        description: "superuser authentication"
        type: "string"
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            example:
              - studentNumber: "the student number of user"
                testcase: 
                  - forQuestion: "the question for"
                    input: "question inputs"
                    output: " the question output"
                codes:
                  - forQuestion: "the questionFor"
                    code: "the path of uploaded code"
                    
              
        "500":
          description: "error will be returned"
    post:
      tags:
      - "User"
      summary: "Create user"
      description: "This can only be done by mr hashemi or superuser."
      operationId: "createUser"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Created user object"
        required: true
        schema:
          type: "object"
          example:
            studentNumber: "user student number"
            password: "password"
      responses:
        "201":
          description: "successful operation"
          schema:
            type: "object"
            example:
              user:
                studentNumber: "the student number of user"
                testcase: 
                  - forQuestion: "the question for"
                    input: "question inputs"
                    output: " the question output"
                codes:
                  - forQuestion: "the questionFor"
                    code: "the path of uploaded code"
              token: "user token"
        "500":
          description: "error will be returned"
  /user/{studentNumber}:
    get:
      tags:
      - "User"
      summary: "get the specified user"
      description: "this can only be done by superuser (and in future) the user itself"
      operationId: "getUserById"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "studentNumber"
        description: "id of the user"
        required: true
        type: "string"
      responses:
        default:
          description: "returns specified user"
          schema:
            type: "object"
            example:
              studentNumber: "the student number of user"
              testcase: 
                - forQuestion: "the question for"
                  input: "question inputs"
                  output: " the question output"
              codes:
                - forQuestion: "the question For"
                  code: "the path of uploaded code"
        "500":
          description: "error will be returned"
    patch:
      tags:
      - "User"
      summary: "update user"
      description: "this can only be done by superuser (and in future) the user itself."
      operationId: "updateUser"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "studentNumber"
        in: "path"
        description: "id of user which needs to be updated"
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "Updated user object"
        required: true
        schema:
          type: "object"
          example:
            studentNumber: "updated student number"
            password: "updated password"
      - in: "header"
        name: "Authorization"
        description: "superuser auth"
        required: true
        type: "string"
      responses:
        default:
          description: "updated user"
          schema:
            type: "object"
            example:
              user:
                studentNumber: "the student number of user"
                testcase: 
                  - forQuestion: "the question for"
                    input: "question inputs"
                    output: " the question output"
                codes:
                  - forQuestion: "the questionFor"
                    code: "the path of uploaded code"
              message: "user updated successfully"
        "500":
          description: "error will be displayed "
    delete:
      tags:
       - "User"
      summary: "Delete user"
      description: "This can only be done by the logged in user or super admin."
      operationId: "deleteUser"
      produces:
      - "application/json"
      parameters:
      - name: "studentNumber"
        in: "path"
        description: "The name that needs to be deleted"
        required: true
        type: "string"
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"
      responses:
        default:
          description: "successfully removed and returns removed user"
          schema:
            type: "object"
            example:
              removedUser: 
                studentNumber: "the student number of user"
                testcase: 
                  - forQuestion: "the question for"
                    input: "question inputs"
                    output: " the question output"
                codes:
                  - forQuestion: "the questionFor"
                    code: "the path of uploaded code"
              message: "user successfully removed"
        "500":
          description: "error will be returned"
  /user/login:
    post:
      tags:
      - "User"
      summary: "login into account"
      description: "This can be done by anyone."
      operationId: "userlogin"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "request body"
        schema:
          type: "object"
          example:
            studentNumber: "user student's number"
            password: "user password"
        required: true
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            example:
              user:
                studentNumber: "the student number of user"
                testcase: 
                  - 
                codes:
                  - 
              token: "the generated token"
        "400":
          description: "error will be returned, propably bad request"
  /user/me/logout:
    post:
      tags:
      - "User"
      summary: "logout of account"
      description: "This can only be done by user itself."
      operationId: "userlogout"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "Authorization"
        description: "user auth token"
        type: "string"
        required: true
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            example:
              message: "logged out successfully"
        "400":
          description: "error will be returned, propably bad request"
  /user/me/changepass:
    post:
      tags:
      - "User"
      summary: "change the password of user"
      description: "This can only be done by user itself."
      operationId: "userChangeOass"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "Authorization"
        description: "user auth token"
        type: "string"
        required: true
      - in : "body"
        name : "body"
        description: " the body of password"
        schema:
          type: "object"
          example:
            newPassword: "the new password of "
        required: true
        
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            example:
              message: "logged out successfully"
        "400":
          description: "error will be returned, propably bad request"
  /user/me/getquestion:
    post:
      tags:
      - "User"
      summary: "gets all of avaliable questions"
      description: "This can only be done by user itself."
      operationId: "userGetQeustion"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "Authorization"
        description: "user auth token"
        type: "string"
        required: true
      responses:
        "200":
          description: "returns all questions with state attached to it.state can be 'notTouched' or 'finished' or 'workingOn"
          schema:
            type: "object"
            example:
             -  _id: "the id used in db"
                forDate: "the for date"
                name: "name of the question"
                body: "the body of question"
                examples:
                  - _id: "id of example"
                    input: "example of input"
                    output: "example of output"
                testGeneratorPath: "the path of testgenerator file"
                answerPath: "the path of answer file"
                state: "the state of questions ."
        "500":
          description: "error will be returned"

  /question/{id}/testcase/ :
    get:
      tags:
      - "Question"
      summary: "gets specified question"
      description: "This can only be done by user itself."
      operationId: "userGetQeustionById"
      produces:
      - "application/json"
      parameters:
      - in: "header"
        name: "Authorization"
        description: "user auth token"
        type: "string"
        required: true
      - in: "path"
        name: "id"
        description: "the id of question "
        type: "string"
        required: true
      responses:
        "200":
          description: "returns all questions with state attached to it.state can be 'notTouched' or 'finished' or 'workingOn"
          schema:
            type: "object"
            example:
             -  question: 
                  _id: "the id used in db"
                  forDate: "the for date"
                  name: "name of the question"
                  body: "the body of question"
                  examples:
                    - _id: "id of example"
                      input: "example of input"
                      output: "example of output"
                  author: "the id of question author"
                  testGeneratorPath: "the path of testgenerator file"
                  answerPath: "the path of answer file"
                testCase: "string representing testCases"
                
        "500":
          description: "error will be returned"
  /question/:
    post:
      tags:
       - "Question"
      summary: "creates new question"
      description: "This can be done only by superuser or question admin. notice content of the request should be FORM-DATA"
      operationId: "createQuestion"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - name: "date"
        in: "formData"
        description: "timestamp of the date"
        required: true
        type: "string"
      - name: "name"
        in: "formData"
        description: "the name of the question"
        required: true
        type: "string"
      - name: "body"
        in: "formData"
        required: true
        description: "the body if question in string"
        type: "string"
      - name: "examples"
        in: "formData"
        required: true
        description: "an stringified array of object containing inputs and outputs => {input:sth,output:sth}"
        type: "string"
      - name: "testGenerator"
        in: "formData"
        required: true
        type: "file"
        description: "the file of testGenerator . notice it can be only one file"
      - name: "answer"
        in: "formData"
        required: true
        type: "file"
        description: "the file of answer . notice it can be only one file"
      - name: "score"
        in: "formData"
        required: true
        description: "the score of question"
        type: "number"
      - name: "isWeb"
        in: "formData"
        required: true
        type: "boolean"
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"
        description: "the bearer auth"
      responses:
        "201":
          description: "successfully creates question and send its object"
          schema:
            $ref: "#/definitions/Question"

        "400":
          description: "Bad request .error will be returned"  
    get:
      tags:
        - "Question"
      description: "this can be done by super user or question admin or user"
      summary: "returns all questions"
      produces:
        - "application/json"
      parameters:
        - name: "Authorization"
          in: "header"
          type: "string"
          required: true
      responses:
        "200":
          description: "return the list of all questions"
          schema:
           $ref: "#/definitions/Question"
  /question/submit:
    post:
      tags:
        - "Question"
      summary : "submits the answer"
      description: "can only be done by user"
      consumes:
       - "multipart/form-data"
      produces:
        - "application/json"
      parameters:
        - name: "questionID"
          in : "formData"
          description: "the id of the question"
          type: "string"
          required: true
        - name: "code" 
          in: "formData"
          type: "file"
          description: "submitting code "
          required: true
        - name: "output"
          in: "formData"
          type: "file"
          description: "text file of output"
          required: true
        - name: "Authorization"
          in: "header"
          description: "user auth"
          type: "string"
      responses:
        "200":
          description: "returns something good"
          schema:
            type: "object"
            example :
              message: "you solved it :)"
        "406":
          description: "shows that code didn't word"
          schema:
            type: "object"
            example: 
              message: "output was wrong. try harder"
        "500":
          description: "sth bad happend, error will be send"
  /question/{id}:
    get:
      tags:
        - "Question"
      description: "it can be done by user & superuser & question admin"
      summary: " returns specified question"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "id"
          required: true
          type: "string"
        - in: "header"
          name: "Authorization"
          required: true
          type: "string"
      responses:
        "200":
           description: " return question with specified name"
           schema: 
             $ref: "#/definitions/Question"
        "500":
          description: "error message will be printed"
    delete:
      tags:
        - "Question"
      description: "it can only be done by superuser and question admin"
      summary: "delete specified question"
      produces:
        - "application/json"
      parameters:
        - in: "path"
          name: "id"
          required: true
          type: "string"
        - in: "header"
          name: "Authorization"
          required: true
          type: "string"
      responses:
        "200":
          description: "returns removed question and a message"
          schema:
            example:
              removedQuestion: 
                _id: "the id used in db"
                forDate: "the for date"
                name: "name of the question"
                body: "the body of question"
                examples:
                  - _id: "id of example"
                    input: "example of input"
                    output: "example of output"
                testGeneratorPath: "the path of testgenerator file"
                answerPath: "the path of answer file"
                score: "score of question"
              message : "successfully removed"
    patch:
      tags:
        - "Question"
      summary: "updates specified question"
      description: "This can be done only by superuser or question admin. notice content of the request should be FORM-DATA. notice not all of these fields and files should be present"
      operationId: "updateQuestion"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        required: true
        type: "string"
        description: "id of question in the db"
      - name: "forDate"
        in: "formData"
        description: "the specified date in string"
        required: true
        type: "string"
      - name: "name"
        in: "formData"
        description: "the name of the question"
        required: true
        type: "string"
      - name: "body"
        in: "formData"
        required: true
        description: "the body if question in string"
        type: "string"
      - name: "examples"
        in: "formData"
        required: true
        description: "an stringified array of object containing inputs and outputs => {input:sth,output:sth}"
        type: "string"
      - name: "testGenerator"
        in: "formData"
        required: true
        type: "file"
        description: "the file of testGenerator . notice it can be only one file"
      - name: "answer"
        in: "formData"
        required: true
        type: "file"
        description: "the file of answer . notice it can be only one file"
      - name: "Authorization"
        in: "header"
        required: true
        type: "string"
        description: "the bearer auth"
      responses:
        "200":
          description: "returns updated question and a message"
          schema:
            example:
              updatedQuestion: 
                _id: "the id used in db"
                forDate: "the for date"
                name: "name of the question"
                body: "the body of question"
                examples:
                  - _id: "id of example"
                    input: "example of input"
                    output: "example of output"
                testGeneratorPath: "the path of testgenerator file"
                answerPath: "the path of answer file"
                score: "score of question"
              message : "successfully updated"

        "500":
          description: "error will be returned"

    
  /scoreboard/ :
    get:
      tags:
        - "Scoreboard"
      summary: "getting the scores of all users"
      description : "returns all of users rank based on most scores and penalties . everyone can access to this page"
      produces: 
      - "application/json"
      responses:
        "200": 
          description: "returns list of info objects"
          schema: 
            example:
              newbies: 
                - studentNumber: "99 ie guys"
                  penalty: "submittedDate - questionCreated date"
                  score : "studentScore"
              notNoob:
                - studentNumber: "non 99 ie guys"
                  penalty: "submittedDate - questionCreated date"
                  score : "studentScore"
definitions:
  SuperUser:
    type: "object"
    properties:
      username:
        type: "string"
      password:
        type: "string"
      tokens:
        type: "string"
    required:
      - username
      - password 
    example:
       username: superuser
       password: superuserPass
    xml:
      name: "superuser"
  QuestionAdmin:
    type: "object"
    properties:
      username:
        type: "integer"
      password :
        type: "string"
      questions: 
        type: "array"
        items:
          $ref: "#/definitions/Question"
    required:
      - username 
      - password 
    example:
        username: "questionAdminUsername"
        password: "qAdminPass"
        questions: "[list of questions]"
  User:
    type: "object"
    properties:
      studentNumber:
        type: "integer"
      password:
        type: "string"
        example:
      testCases:
        type: "string"
        description: "arrays of testcases"
  Question:
    type: "object"
    properties:
      _id:
        type: "string"
        example: "the id of question used in db"
      forDate:
        type: "string"
        example: "for date"
      name:
        type: "string"
        example: "name of the question"
      body:
        type: "string"
        example: "body of the question"
      examples:
        type: "array"
        items:
          type: "object"
          properties:
            input:
              type: "string"
              example: "example of input"
            output:
              type: "string"
              example: "example of output"
      testGeneratorPath:
        type: "string"
      answerPath:
        type: "string"
      score: 
        type: "number"
        example: "score (as number)"
      isWeb:
        type: "boolean"
        example: "1, true, yes / 0, false, no"