swagger.yml

swagger: "2.0"
info:
  description: "This is the oficial documentation for the EasyPoll API. If you have any problems or requests, please contact us on GitHub."
  version: "1.0.0"
  title: "EasyPoll"
  contact:
    email: "noreply@easypoll.com.br"
basePath: "/v1"
tags:
- name: "auth"
  description: "Operations about authentication"
- name: "poll"
  description: "Operations to get, create, update and delete polls"
- name: "vote"
  description: "Operations to vote"
schemes:
- "http"
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
paths:
  /login:
    post:
      tags:
        - auth
      summary: Login to the application
      description: Authenticates an user and returns a token to be used in requests
      operationId: "loginUser"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Account credentials"
          required: true
          schema:
            type: object
            properties:
              email:
                type: string
                description: Email of the account
              password:
                type: string
                description: Password of the account
                format: password
            required:
              - email
              - password
      responses:
        200:
          description: Login successful
          schema:
            allOf:
              - $ref: '#/definitions/Token'
              - type: object
                properties:
                  user:
                    $ref: '#/definitions/User'
        400:
          description: Incorrect password or invalid input
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Email not registered
          schema:
            $ref: '#/definitions/Error'
        422:
          description: Missing required fields
  /register:
    post:
      tags:
        - auth
      summary: Create a new account
      description: Create a new account and returns a token to be used in requests
      operationId: "registerUser"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Account details"
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
                description: Name of the user
              email:
                type: string
                description: Email of the account
              password:
                type: string
                description: Password of the account
                format: password
            required:
              - name
              - email
              - password
      responses:
        200:
          description: Account created
          schema:
            allOf:
              - $ref: '#/definitions/Token'
              - type: object
                properties:
                  user:
                    $ref: '#/definitions/User'
        400:
          description: Email already registered or invalid input
        422:
          description: Missing required fields
  /user:
    get:
      tags:
        - auth
      summary: Get the logged user info
      security:
        - Bearer: []
      description: Get the authenticated user account details
      operationId: "getAuthenticatedUser"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      responses:
        200:
          description: Return the account of the authenticated user
          schema:
            allOf:
              - $ref: '#/definitions/User'
        401:
          description: Invalid token
  /polls:
    get:
      tags:
      - "poll"
      summary: "List all polls"
      description: "Gets a list with all the polls in the database"
      operationId: "getPolls"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      responses:
        200:
          schema:
            type: array
            items:
              $ref: "#/definitions/Poll"
          description: "Poll list fetched successfully"
    post:
      tags:
      - "poll"
      summary: "Create a new poll"
      description: "Inserts a new poll in the database"
      operationId: "createPoll"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Poll that will be created"
        required: true
        schema:
          allOf:
            - $ref: "#/definitions/PollRequest"
          required:
            - question
            - answers
            - multipleAnswers
      responses:
        200:
          schema:
            $ref: "#/definitions/Poll"
          description: "Poll created"
        400:
          description: "Invalid input"
        422:
          description: "Missing required fields"
  /polls/{id}:
    get:
      tags:
      - "poll"
      summary: "Display a single poll by id"
      description: "Gets a single poll by id"
      operationId: "getPollById"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
        - name: id
          in: path
          type: integer
          required: true
          description: The id of the poll
      responses:
        200:
          schema:
              $ref: "#/definitions/Poll"
          description: "Poll fetched successfully"
        404:
          description: "Resource not found"
    put:
      tags:
      - "poll"
      summary: "Update a poll by id"
      description: |
        Updates the whole poll object with a new one

        Unspecified optional fields will be counted as zero-value and will be overwritten
      operationId: "updatePollById"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: id
        in: path
        type: integer
        required: true
        description: The id of the poll
      - in: "body"
        name: "body"
        description: "New poll data"
        required: true
        schema:
          allOf:
            - $ref: "#/definitions/PollRequest"
          required:
            - question
            - answers
            - multipleAnswers
      responses:
        200:
          schema:
            $ref: "#/definitions/Poll"
          description: "Poll updated"
        400:
          description: "Invalid input"
        404:
          description: "Resource not found"
        422:
          description: "Missing required fields"
    patch:
      tags:
      - "poll"
      summary: "Update (part of) a poll by id"
      description: |
        Updates (part of) a poll properties, all fields are optional

        Unspecified fields will be ignored and won't be updated
      operationId: "patchPollById"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: id
        in: path
        type: integer
        required: true
        description: The id of the poll
      - in: "body"
        name: "body"
        description: "Properties of the poll that will be updated"
        required: true
        schema:
          $ref: "#/definitions/PollRequest"
      responses:
        200:
          schema:
            $ref: "#/definitions/Poll"
          description: "Poll updated"
        400:
          description: "Invalid input"
        404:
          description: "Resource not found"
    delete:
      tags:
      - "poll"
      summary: "Delete a poll by id"
      description: "Removes a poll from the database by id"
      operationId: "deletePollById"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
        - name: id
          in: path
          type: integer
          required: true
          description: The id of the poll
      responses:
        204:
          description: "Poll deleted"
        404:
          description: "Resource not found"
  /polls/{id}/votes:
    post:
      tags:
      - "vote"
      summary: "Votes in answers of a poll"
      description: |
        Adds one vote to answers of a poll, the request body is an array with integers, each number is the index of the answer

        Sending [1, 3, 2] will add one vote to the 2nd, 4th and 3rd answers of the poll

        You can only send more than one value in the array if the poll accepts multiple answers

        Repeated numbers will be counted as one
      operationId: "addVotePoll"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: id
        in: path
        type: integer
        required: true
        description: The id of the poll
      - in: "body"
        name: "body"
        description: "Array with answers to be voted"
        required: true
        schema:
          type: array
          items:
            type: integer
      responses:
        204:
          description: "Vote(s) added"
        400:
          description: "Invalid input"
          schema:
            $ref: '#/definitions/Error'
        404:
          description: "Resource not found"
        422:
          description: "Missing required fields"
definitions:
  Poll:
    type: object
    properties:
      id:
        type: integer
      question:
        type: string
        example: "What's your favorite color?"
      answers:
        type: array
        items:
          $ref: '#/definitions/Answer'
      votes:
        type: integer
        x-omitempty: false
      multipleAnswers:
        type: boolean
      createdAt:
        type: string
        format: date-time
  PollRequest:
    type: object
    properties:
      question:
        type: string
        example: "What's your favorite color?"
      answers:
        type: array
        items:
          $ref: '#/definitions/Answer'
      multipleAnswers:
        type: boolean
  Answer:
    type: object
    properties:
      title:
        type: string
        example: "Blue"
      votes:
        type: integer
        x-omitempty: false
  Token:
    type: object
    properties:
      token:
        type: string
        example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjEsImlhdCI6MTUzMzY2MTY0Mn0.w_qI2tv8imANq_ys_ZKvLtrGItd7hrfRjifJoYSJzfo'
  User:
    type: object
    properties:
      name:
        type: string
        example: 'John Doe'
        description: 'Name of the user'
      email:
        type: string
        example: 'john@doe.com'
        description: 'Email of the user'
      password:
        type: string
        example: 'secret'
        format: password
        description: 'Password of the user'
  Error:
    type: object
    properties:
      code:
        type: integer
        example: 622
      message:
        type: string
        example: "error message"