swagger.yaml

---
swagger: "2.0"
info:
  description: "For Iteration 2"
  version: "1.0.0"
  title: "Today's Announcement + API"
basePath: "/v1"
schemes:
- "https"
- "http"
produces:
- "application/json"
paths:
  /announcement/manage:
    get:
      tags:
      - "Admin"
      - "Applicant"
      summary: "Manage All Announcements"
      description: "For system admin and applicant, get a list of pending announcements.\
        \ Applicants will get their own announcements while admin will get all unpushed\
        \ announcements.\n"
      parameters:
      - name: "managerid"
        in: "header"
        description: "Unique ID of a manager (applicant or admin)"
        required: true
        type: "string"
      responses:
        200:
          description: "An array of announcements for management"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/AnnouncementForManagement"
        404:
          description: "Announcement not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/manage/approve:
    put:
      tags:
      - "Admin"
      summary: "Approve an announcement"
      description: "For system admin, approve a pending announcement.\n"
      parameters:
      - name: "aid"
        in: "query"
        description: "Unique ID of an announcement"
        required: true
        type: "string"
      - name: "managerid"
        in: "header"
        description: "Unique ID of a manager (admin)"
        required: true
        type: "string"
      responses:
        200:
          description: "Success, OK"
        403:
          description: "Not authorized to approve"
        404:
          description: "Announcement not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/manage/bydate:
    get:
      tags:
      - "Admin"
      - "Applicant"
      summary: "Manage Announcement By Date"
      description: "For system admin and applicant, get a list of all (penging/pushed/expired)\
        \ announcements by date. Applicants will get their own announcements while\
        \ admin will get all announcements.\n"
      parameters:
      - name: "datefrom"
        in: "query"
        description: "Start date of announcement request"
        required: true
        type: "string"
        format: "date"
      - name: "dateto"
        in: "query"
        description: "End date of announcement request"
        required: true
        type: "string"
        format: "date"
      - name: "managerid"
        in: "header"
        description: "Unique ID of a manager (applicant or admin)"
        required: true
        type: "string"
      responses:
        200:
          description: "An array of announcements for management"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/AnnouncementForManagement"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/manage/decline:
    put:
      tags:
      - "Admin"
      summary: "Decline an announcement"
      description: "For system admin, decline a pending announcement.\n"
      parameters:
      - name: "aid"
        in: "query"
        description: "Unique ID of an announcement"
        required: true
        type: "string"
      - name: "managerid"
        in: "header"
        description: "Unique ID of a manager (admin)"
        required: true
        type: "string"
      responses:
        200:
          description: "Success, OK"
        403:
          description: "Not authorized to decline"
        404:
          description: "Announcement not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/manage/delete:
    delete:
      tags:
      - "Admin"
      - "Applicant"
      summary: "Delete an announcement"
      description: "For system admin and applicant, delete an announcement. Applicants\
        \ can delete their own UNPUSHED announcement while admin can delete all announcements.\n"
      parameters:
      - name: "aid"
        in: "query"
        description: "Unique ID of an announcement"
        required: true
        type: "string"
      - name: "managerid"
        in: "header"
        description: "Unique ID of a manager (admin)"
        required: true
        type: "string"
      responses:
        200:
          description: "Success, OK"
        403:
          description: "Not authorized to delete"
        404:
          description: "Announcement not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/manage/modify:
    put:
      tags:
      - "Admin"
      - "Applicant"
      summary: "Modify an announcement"
      description: "For system admin and applicant, modify an announcement. Announcement\
        \ modified by applicants will automatically get Unapproved status. Pushed\
        \ or expired announcements can onli be modified by admin.\n"
      parameters:
      - name: "aid"
        in: "query"
        description: "Unique ID of an announcement"
        required: true
        type: "string"
      - name: "managerid"
        in: "header"
        description: "Unique ID of a manager"
        required: true
        type: "string"
      - in: "body"
        name: "new_announcement"
        description: "Modified announcement"
        required: true
        schema:
          $ref: "#/definitions/DetailedAnnouncement"
      responses:
        200:
          description: "Success, OK"
        403:
          description: "Not authorized to modify"
        404:
          description: "Announcement not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/submit:
    post:
      tags:
      - "Applicant"
      summary: "Submit a new announcement"
      description: "For applicant, submit a new announcement. No login needed and\
        \ an email containing access code will be sent to the applicant.\n"
      parameters:
      - in: "body"
        name: "new_announcement"
        description: "Submitted new announcement"
        required: true
        schema:
          $ref: "#/definitions/DetailedAnnouncement"
      responses:
        201:
          description: "Success, Created"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/view:
    get:
      tags:
      - "User"
      summary: "View Today's Announcements"
      description: "For mobile users, get a list of announcements pushed today.\n"
      parameters: []
      responses:
        200:
          description: "An array of announcements"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Announcement"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/view/attend:
    post:
      tags:
      - "User"
      summary: "Attend Event"
      description: "For mobile users, get announcements of a specific date period.\n"
      parameters:
      - name: "aid"
        in: "query"
        description: "Unique ID of an announcement"
        required: true
        type: "string"
      - in: "body"
        name: "userinfo"
        description: "User information for attending an event"
        required: true
        schema:
          $ref: "#/definitions/PersonalInfo"
      responses:
        200:
          description: "Success, OK"
        403:
          description: "Unauthorized to attend event"
        404:
          description: "Event not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/view/bydate:
    get:
      tags:
      - "User"
      summary: "View Announcement By Date"
      description: "For mobile users, get announcements of a specific date period.\n"
      parameters:
      - name: "datefrom"
        in: "query"
        description: "Start date of announcement request"
        required: true
        type: "string"
        format: "date"
      - name: "dateto"
        in: "query"
        description: "End date of announcement request"
        required: true
        type: "string"
        format: "date"
      responses:
        200:
          description: "An array of announcements"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Announcement"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /announcement/view/detail:
    get:
      tags:
      - "User"
      summary: "View Announcement Detail"
      description: "For mobile users, get detail of a pushed announcement.\n"
      parameters:
      - name: "aid"
        in: "query"
        description: "Unique ID of an announcement"
        required: true
        type: "string"
      responses:
        200:
          description: "Requested detailed announcement"
          schema:
            $ref: "#/definitions/DetailedAnnouncement"
        404:
          description: "Announcement not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /user/access:
    post:
      tags:
      - "Applicant"
      summary: "Applicant access by code"
      description: "For applicant, get access to the system with access code.\n"
      parameters:
      - in: "body"
        name: "access_code"
        description: "Applicant access code"
        required: true
        schema:
          $ref: "#/definitions/AccessCode"
      responses:
        200:
          description: "Success, OK"
        404:
          description: "Wrong access code"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /user/login:
    post:
      tags:
      - "Admin"
      summary: "Admin login"
      description: "For admin, login to the system.\n"
      parameters:
      - in: "body"
        name: "login_info"
        description: "Admin login info"
        required: true
        schema:
          $ref: "#/definitions/LoginInfo"
      responses:
        200:
          description: "Success, OK"
        404:
          description: "Wrong login info"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /user/retrieve_code:
    post:
      tags:
      - "Applicant"
      summary: "Retrieve access code by email"
      description: "For applicant, retrieve access code by email. A new access code\
        \ will be sent by email.\n"
      parameters:
      - name: "email"
        in: "query"
        description: "Applicant email address"
        required: true
        type: "string"
      responses:
        200:
          description: "Success, OK"
        404:
          description: "Email not exists"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
definitions:
  Error:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      message:
        type: "string"
      fields:
        type: "string"
  Location:
    type: "object"
    required:
    - "lat"
    - "lng"
    properties:
      lat:
        type: "number"
        format: "double"
        description: "Latitude of a location."
      lng:
        type: "number"
        format: "double"
        description: "Longitude of a location."
  Announcement:
    type: "object"
    required:
    - "hostInfo"
    - "id"
    - "isEvent"
    - "pushDate"
    - "summary"
    - "title"
    properties:
      id:
        type: "integer"
        format: "int32"
        description: "Unique ID of an announcement."
      title:
        type: "string"
        description: "Title of an announcement."
      summary:
        type: "string"
        description: "Brief summary of an announcement."
      pushDate:
        type: "string"
        format: "date"
        description: "Push date of an announcement."
      isEvent:
        type: "boolean"
        description: "Whether or not the announcement is an event announcement."
      location:
        $ref: "#/definitions/Location"
      foodProvided:
        type: "boolean"
        description: "Whether or not the event provides food. (Event only)"
      hostInfo:
        $ref: "#/definitions/PersonalInfo"
  DetailedAnnouncement:
    allOf:
    - $ref: "#/definitions/Announcement"
    - properties:
        detail:
          type: "string"
          description: "Detailed description of an announcement"
  AnnouncementForManagement:
    allOf:
    - $ref: "#/definitions/Announcement"
    - properties:
        submitDate:
          type: "string"
          format: "date"
          description: "Submit date of an announcement."
        status:
          type: "string"
          description: "Current status of an announcement."
          enum:
          - "Unapproved"
          - "Approved"
          - "Declined"
          - "Pushed"
          - "Expired"
          default: "Unapproved"
  PersonalInfo:
    type: "object"
    required:
    - "firstName"
    properties:
      firstName:
        type: "string"
        description: "First name of a user."
      lastName:
        type: "string"
        description: "Last name of a user."
      organization:
        type: "string"
        description: "Organization of a user."
      email:
        type: "string"
        description: "Email address of a user."
      phone:
        type: "string"
        description: "Phone number of a user."
  LoginInfo:
    type: "object"
    required:
    - "password"
    - "username"
    properties:
      username:
        type: "string"
        description: "Admin username."
      password:
        type: "string"
        format: "password"
        description: "Admin password."
  AccessCode:
    type: "object"
    required:
    - "accessCode"
    properties:
      accessCode:
        type: "string"
        format: "password"
        description: "Applicant access code."