openapi: "3.0.3"

info:
  title: Kwiz API
  version: "1.0"
  description: |-
    An API for creating and managing quizzes, which supports sign up and authentication.

    [Give it a star on github](https://github.com/ikrishagarwal/kwiz-api)

servers:
  - url: /api

components:
  schemas:
    Kwizes:
      type: object
      properties:
        questions:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
              optionA:
                type: string
              optionB:
                type: string
              optionC:
                type: string
              optionD:
                type: string
            required:
              - question
              - optionA
              - optionB
      required:
        - questions

    Kwiz:
      type: object
      properties:
        kwiz_id:
          type: string
        id:
          type: string
        question:
          type: string
        optionA:
          type: string
        optionB:
          type: string
        optionC:
          type: string
        optionD:
          type: string

    KwizResponse:
      type: object
      properties:
        questions:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
              optionA:
                type: string
              optionB:
                type: string
              optionC:
                type: string
              optionD:
                type: string
        kwiz_id:
          type: string

    QuestionResponse:
      type: object
      properties:
        id:
          type: string
        kwiz_id:
          type: string
        question:
          type: string
        optionA:
          type: string
        optionB:
          type: string
        optionC:
          type: string
        optionD:
          type: string

    Question:
      type: object
      properties:
        question:
          type: string
        optionA:
          type: string
        optionB:
          type: string
        optionC:
          type: string
        optionD:
          type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

tags:
  - name: v1
    description: First rollout

paths:
  /auth:
    post:
      summary: Get a JWT token
      tags: [v1]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
              required:
                - email
                - password
      responses:
        "200":
          description: Successfully authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                  token:
                    type: string
                    format: jwt
        "401":
          description: Invalid credentials
        "400":
          description: Bad request
        "500":
          description: Internal server error

  /signup:
    post:
      summary: Create a new user
      tags: [v1]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        "201":
          description: User created successfully
        "400":
          description: Invalid credentials
        "409":
          description: User is already signed up
        "500":
          description: Internal Server Error

  /kwizes:
    get:
      summary: Get all Kwizes made by you
      tags: [v1]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of Kwizes
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    kwiz_id:
                      type: string
                    id:
                      type: string
        "400":
          description: Insufficient/Invalid data
        "500":
          description: Internal server error

    post:
      summary: Create a new kwiz
      tags: [v1]
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Kwizes"
      responses:
        "201":
          description: Successfully created a new user
          content:
            application/json:
              schema:
                type: object
                properties:
                  questions:
                    type: array
                    items:
                      type: object
                      properties:
                        question:
                          type: string
                        optionA:
                          type: string
                        optionB:
                          type: string
                        optionC:
                          type: string
                        optionD:
                          type: string
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal server error

  /kwizes/{id}:
    get:
      summary: Get a specific Kwiz by ID
      tags: [v1]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string

      security:
        - bearerAuth: []

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kwiz"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden, you don't have kwiz access
        "500":
          description: Internal server error

    delete:
      summary: Delete a specific Kwiz by ID
      tags: [v1]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string

      security:
        - bearerAuth: []

      responses:
        "204":
          description: Deleted Successfully
        "401":
          description: Unauthorized
        "404":
          description: Kwiz not found
        "500":
          description: Internal server error

    post:
      summary: Add a question to a Kwiz by ID
      tags: [v1]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string

      security:
        - bearerAuth: []

      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Question"

      responses:
        "201":
          description: Question added successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuestionResponse"
        "400":
          description: Missing required fields
        "401":
          description: Unauthorized
        "404":
          description: Kwiz not found
        "500":
          description: Internal server error

  /questions/{id}:
    get:
      summary: Get a question by it's ID
      tags: [v1]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string

      security:
        - bearerAuth: []

      responses:
        "200":
          description: Successfully retrieved the question
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuestionResponse"
        "404":
          description: Question not found
        "500":
          description: Internal server Error

    delete:
      summary: Delete a question by ID
      tags: [v1]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string

      security:
        - bearerAuth: []

      responses:
        "204":
          description: Successfully deleted the question
        "401":
          description: Unauthorized
        "403":
          description: Forbidden, you can't access the question
        "404":
          description: Question not found
        "500":
          description: Internal server error

    put:
      summary: Edit an existing question by ID
      tags: [v1]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string

      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Question"

      security:
        - bearerAuth: []

      responses:
        "200":
          description: Successfully edited the question
        "401":
          description: Unauthorized
        "403":
          description: Forbidden, you can't access the question
        "404":
          description: Question not found
        "500":
          description: Internal server error