hackathon/schema/schema.yaml

openapi: "3.0.0"
info:
  version: 0.1.0
  title: Swagger Hackathon
  description: A hackathon, hosted in JIS API specification created by Hamza Ali.
  contact:
    name: Hamza Ali
    email: me@hamzantal.pw
  license:
    name: MIT License
    url: "https://hamza.mit-license.org/"

paths:
  /auth/code:
    get:
      description: Generate oauth exchange url.
      tags: ["Auth"]
      operationId: gen oauth
      parameters:
        - name: callback
          in: query
          required: true
          schema:
            type: string
            format: uri
      responses:
        '200':
          description: OAuth Consent Page URI.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentPage"
        default:
          $ref: "#/components/responses/DefaultResponse"

  /auth/authorize:
    get:
      description: Authorization response callback location.
      tags: ["Auth"]
      operationId: authorize callback
      parameters:
        - name: state
          in: query
          required: true
          schema:
            type: string
        - name: code
          in: query
          required: true
          schema:
            type: string
      responses:
        '302':
          description: Redirect to webpage.
          headers:
            Location:
              schema:
                type: string
                format: uri
        default:
          $ref: "#/components/responses/DefaultResponse"

  /auth/token:
    delete:
      tags: ["Auth"]
      operationId: delete token
      x-go-middlewares: ["token"]
      parameters:
        - $ref: "#/components/parameters/Token"
        - name: all
          in: query
          required: true
          schema:
            type: boolean
      responses:
        '204':
          description: User successfully logged out.
        default:
          $ref: "#/components/responses/DefaultResponse"

  /users/me:
    get:
      description: Get self user information.
      tags: ["Users"]
      operationId: get me
      x-go-middlewares: ["token"]
      parameters:
        - $ref: "#/components/parameters/Token"
      responses:
        '200':
          description: User information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        default:
          $ref: "#/components/responses/DefaultResponse"
    put:
      description: Update self user.
      tags: ["Users"]
      operationId: modify user
      x-go-middlewares: ["token"]
      parameters:
        - $ref: "#/components/parameters/Token"
      requestBody:
        description: Modified user information.
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - grade_level
              properties:
                name:
                  type: string
                grade_level:
                  type: integer
      responses:
        '200':
          description: New user data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        default:
          $ref: "#/components/responses/DefaultResponse"

  /users/email:
    get:
      description: |-
        Get user info by email.
        Requires admin to get user info not equal to the owner of the token.        
      tags: ["Users"]
      operationId: get user by email
      x-go-middlewares: ["token"]
      parameters:
        - $ref: "#/components/parameters/Token"
        - name: email
          in: query
          description: User email.
          required: true
          schema:
            type: string
            format: email
      responses:
        '200':
          description: User information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        default:
          $ref: "#/components/responses/DefaultResponse"
    put:
      description: Update another user. Requires admin.
      tags: ["Users"]
      operationId: modify other user
      x-go-middlewares: ["token", "admin_token"]
      parameters:
        - name: token
          in: cookie
          description: User authentication token.
          required: true
          schema:
            type: string
        - name: email
          in: query
          description: User email.
          required: true
          schema:
            type: string
            format: email
      requestBody:
        description: Modified user information.
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - picture
                - grade_level
                - teacher
                - admin
              properties:
                name:
                  type: string
                new_email:
                  type: string
                  format: email
                picture:
                  type: string
                  format: uri
                grade_level:
                  type: integer
                teacher:
                  type: boolean
                admin:
                  type: boolean

      responses:
        '200':
          description: User information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        default:
          $ref: "#/components/responses/DefaultResponse"

  /users/all:
    get:
      description: Get all users. Requires admin.
      tags: ["Users"]
      operationId: get all users
      x-go-middlewares: ["token", "admin_token"]
      parameters:
        - $ref: "#/components/parameters/Token"
      responses:
        '200':
          description: All user information.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        default:
          $ref: "#/components/responses/DefaultResponse"

components:
  parameters:
    Token:
      name: token
      in: cookie
      description: User authentication token.
      required: true
      schema:
        type: string

  responses:
    DefaultResponse:
      description: Unexpected server error or invalid user input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    ConsentPage:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
    User:
      type: object
      required:
        - id
        - name
        - email
        - picture
        - teacher
        - admin
        - created_at
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        picture:
          type: string
          format: uri
        grade_level:
          type: integer
          description: GradeLevel is only present if teacher is false.
        teacher:
          type: boolean
        admin:
          type: boolean
        created_at:
          type: string
          format: date-time

    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string