swagger: "2.0"
info:
  version: "1.0.0"
  title: "Mad Devs Comedian"
  contact:
    email: "fedorenko.tolik@gmail.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "comedian.maddevs.co"
basePath: "/"
tags:
- name: "standups"
  description: "get, list, update and delete standups"
- name: "channels"
  description: "Slack team channels (aka projects) tracked by Comedian"
- name: "standupers"
  description: "Project standupers tracked by Comedian"
- name: "bots"
  description: "Slack team bot settings (configuration)"
schemes:
  - "https"
  - "http"
securityDefinitions:
  Auth:
    description: "Valid Bot Access Token"
    type: apiKey
    name: Authorization
    in: header
paths:
  /healthcheck:
    get:
      summary: "Check if Comedian is healthy"
      produces:
      - "application/json"
      responses:
        200:
          description: "Comedian is healthy"
  /login:
    post:
      summary: "Login with Slack auth"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: body
        name: body
        required: true
        description: login params
        schema:
            $ref: '#/definitions/Login'
      responses:
        400:
          description: "Incorrect data format, double check request body"
        404:
          description: "Comedian was not invited to your Slack. Please, add it and try again"
        200:
          description: "Login successful, returns bot info and slack user info"
          schema:
            type: object
            properties:
              user: 
                type: object
                $ref: "#/definitions/User"
              bot:
                type: object
                $ref: "#/definitions/Bot"
  /event:
    post:
      summary: "Not UI related. Handles Slack events"
      description: "Handles different Slack triggers such as bot removal, or URL verification"
      responses:
        200:
          description: "Success"
        400:
          description: "Returns error description" 
        401:
          description: "verification token does not match" 
  /service-message:
    post:
      summary: "Not UI related. Handles messages from different Comedian services."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: body
        name: body
        required: true
        description: "note: slack attachment has particular structure, learn more at slack documentation"
        schema:
            $ref: '#/definitions/ServiceMessage'
      responses:
        400: 
          description: "incorrect data format"
        200:
          description: "Message handled!"
  /commands:
    post:
      summary: "Not UI related. Handles Slack slash commands requests."
      description: "This endpoint is needed for integration with Slack API"
      responses:
        200:
          description: "Message from Comedian to Slack"
        400: 
          description: "Contains error description"
  /auth:
    get:
      summary: "Not UI related. Handles Comedian distribution into other Slack Teams."
      responses:
        200:
          description: "Renders Comedian login page"
  /v1/bots/{id}:
    get:
      security:
        - Auth: []
      tags:
      - "bots"
      summary: "Retrieve bot from db"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "id of the bot"
        required: true
        type: "integer"
      responses:
        200:
          description: "bot"
          schema:
            $ref: "#/definitions/Bot"
        400:
          description: "Incorrect value for bot id, must be integer"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404:
          description: "Entity does not yet exist"
    patch:
      security:
        - Auth: []
      tags:
      - "bots"
      summary: "Updates a bot in the database with form data"
      description: "Update language, notifier_interval, reminder_repeat_max and reminder_time of the bot"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "id of bot that needs to be updated"
        required: true
        type: "integer"
      - in: body
        name: body
        required: true
        description: Bot params that needs to be updated
        schema:
            $ref: '#/definitions/Bot'
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Bot"
        400:
          description: "Incorrect value for bot id, must be integer or incorrect payload for bot entity"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404:
          description: "Entity does not yet exist"
  /v1/channels:
    get:
      security:
        - Auth: []
      tags:
      - "channels"
      summary: "Returns all channels"
      description: "Returns a map of channel objects"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Channel"
        401:
          description: "Missing/incorrect Bot Access Token"
        500:
          description: "unexpected error occured, need to report to maintainers"
  /v1/channels/{id}:
    patch:
      security:
        - Auth: []
      tags:
      - "channels"
      summary: "Updates a channel in the database"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "id of channel that needs to be updated"
        required: true
        type: "integer"
      - in: body
        name: body
        required: true
        description: Channel params that needs to be updated. Currently only standup time can be modified
        schema:
            $ref: '#/definitions/Channel'
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Channel"
        400:
          description: "Incorrect value for channel id, must be integer or incorrect payload for channel entity"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404:
          description: "Entity does not yet exist"
  /v1/standupers:
    get:
      security:
        - Auth: []
      tags:
      - "standupers"
      summary: "Returns all standupers"
      description: "Returns a map of standuper objects"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Standuper"
        401:
          description: "Missing/incorrect Bot Access Token"
        500:
          description: "unexpected error occured, need to report to maintainers"
  /v1/standupers/{id}:
    patch:
      security:
        - Auth: []
      tags:
      - "standupers"
      summary: "Updates a standuper in the database with form data"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "id of standuper that needs to be updated"
        required: true
        type: "integer"
      - in: body
        name: body
        required: true
        description: Standuper params that needs to be updated. Currently only role can be modified
        schema:
            $ref: '#/definitions/Standuper'
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Standuper"
        400:
          description: "Incorrect value for standuper id, must be integer or incorrect payload for standuper entity"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404:
          description: "Entity does not yet exist"
    delete:
      security:
        - Auth: []
      tags:
      - "standupers"
      summary: "Deletes a standuper"
      description: "Untracks user in channel"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "standuper id to delete"
        required: true
        type: "integer"
        format: "int"
      responses:
        204:
          description: "entity was deleted, returns no content"
        400:
          description: "Incorrect value for standuper id, must be integer or incorrect payload for standuper entity"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404:
          description: "Entity does not yet exist"
        500:
          description: "unexpected error occured, need to report to maintainers"
  /v1/standups:
    get:
      security:
        - Auth: []
      tags:
      - "standups"
      summary: "Returns all standups"
      description: "Returns a map of standup objects"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items: 
              $ref: "#/definitions/Standup"
        401:
          description: "Missing/incorrect Bot Access Token"
        500:
          description: "unexpected error occured, need to report to maintainers"
  /v1/standups/{id}:
    get:
      security:
        - Auth: []
      tags:
      - "standups"
      summary: "Find standup by id"
      description: "Returns a single standup"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "id of a standup to return"
        required: true
        type: "integer"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Standup"
        400:
          description: "Invalid data format"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404: 
          description: "Not found"
        403:
          description: "No access to resource"
        500:
          description: "Internal Error"
    patch:
      security:
        - Auth: []
      tags:
      - "standups"
      summary: "Updates a standup in the database with form data"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "id of standup that needs to be updated"
        required: true
        type: "integer"
      - in: body
        name: body
        required: true
        description: standup params that needs to be updated
        schema:
            $ref: '#/definitions/Standup'
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Standup"
        400:
          description: "Incorrect value for standuper id, must be integer or incorrect payload for standuper entity"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404:
          description: "Entity does not yet exist"
    delete:
      security:
        - Auth: []
      tags:
      - "standups"
      summary: "Deletes a standup"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "standup id to delete"
        required: true
        type: "integer"
        format: "int"
      responses:
        204:
          description: "entity was deleted, returns no content"
        400:
          description: "Incorrect value for standup id, must be integer or incorrect payload for standup entity"
        401:
          description: "Missing/incorrect Bot Access Token or trying to access resource from another workspace"
        404:
          description: "Entity does not yet exist"
        500:
          description: "unexpected error occured, need to report to maintainers"
definitions:
  Login: 
    type: "object"
    required:
      - code
    properties:
      code:
        type: "string"
      redirect_uri:
        type: "string"
  ServiceMessage: 
    type: "object"
    properties:
      team_name:
        type: "string"
      bot_access_token:
        type: "string"
      channel:
        type: "string"
      message:
        type: "string"
  Channel:
    type: "object"
    properties:
      id:
        type: "integer"
      channelName:
        type: "string"
      channel_id:
        type: "string"
      channel_standup_time:
        type: "string"
        example: "11:30"
  Standuper:
    type: "object"
    properties:
      id:
        type: "integer"
      userId:
        type: "string"
      channel_id:
        type: "string"
      submitted_standup_today:
        type: "boolean"
      created:
        type: "string"
        format: date-time
      role_in_channel:
        type: "string"
      real_name: 
        type: "string"
      channel_name: 
        type: "string"
  Standup:
    type: "object"
    properties:
      id:
        type: "integer"
      userId:
        type: "string"
      channel_id:
        type: "string"
      comment:
        type: "string"
        format: "text"
      created:
        type: "string"
      modified:
        type: "string"
      message_ts:
        type: "string"
      team_id:
        type: "string"
  Bot:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      team_id:
        type: "string"
        example: "TB9KS3E13"
      team_name:
        type: "string"
        example: "example"
      language:
        type: "string"
        description: "bot language"
        enum:
        - "ru_RU"
        - "en_US"
      notifier_interval:
        type: "integer"
        format: "int64"
      reminder_repeat_max:
        type: "integer"
        format: "int64"
      reminder_time:
        type: "integer"
        format: "int64"
      reporting_channel:
        type: "string"
        example: "TBA234GH"
      reporting_time:
        type: "string"
        example: "9:00"
      individual_reports_on: 
        type: "boolean"
        example: false
  User:
    type: "object"
    properties:
      id: 
        type: "string"
      team_id: 
        type: "string"
      name: 
        type: "string"
      deleted: 
        type: "boolean"
      color: 
        type: "string"
      real_name: 
        type: "string"
      tz,omitempty: 
        type: "string"
      tz_label: 
        type: "string"
      tz_offset: 
        type: "integer"
      profile: 
        type: "object"
      is_bot: 
        type: "boolean"
      is_admin: 
        type: "boolean"
      is_owner: 
        type: "boolean"
      is_primary_owner: 
        type: "boolean"
      is_restricted: 
        type: "boolean"
      is_ultra_restricted: 
        type: "boolean"
      is_stranger: 
        type: "boolean"
      is_app_user: 
        type: "boolean"
      has_2fa: 
        type: "boolean"
      has_files: 
        type: "boolean"
      presence: 
        type: "string"
      locale: 
        type: "string"