api.yaml

swagger: '2.0'
info:
  version: "0.0.4"
  title: Wave Application
host: localhost:9600
basePath: /
tags:
  - name: "user"
  - name: "session"
schemes:
  - http
paths:
  /users:
    post:
      tags:
      - user
      summary: "Create an account."
      description: ""
      operationId: signupUser
      consumes:
        - "multipart/form-data"
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: "Key user information."
          required: true
          schema:
            $ref: "#/definitions/UserCredentials"
      responses:
        201:
          description: Created
        401:
          description: Unauthorized
          schema:
            $ref: "#/definitions/ForbiddenRequest"
        500:
          description: Internal Server Error
  /users/me:
    get:
      tags:
      - user
      summary: "Get current user's information."
      description: ""
      operationId: myProfile
      consumes: []
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/UserExtended"
        401:
          description: Unauthorized
        500:
          description: Internal Server Error
    put:
      tags:
      - user
      summary: "Update current user's profile."
      description: ""
      operationId: updateMyProfile
      consumes:
        - "multipart/form-data"
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: "New user information."
          required: true
          schema:
            $ref: "#/definitions/UserEdit"
      responses:
        200:
          description: OK
        401:
          description: Unauthorized
        403:
          description: Forbidden
          schema:
            $ref: "#/definitions/ForbiddenRequest"
        500:
          description: Internal Server Error
  /users/{name}:
    get:
      tags:
      - user
      summary: "Get another user's information."
      description: ""
      operationId: usersProfile
      consumes: []
      produces:
        - application/json
      parameters:
      - in: path
        name: name
        type: string
        required: true
        description: Target username.
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/UserExtended"
        500:
          description: Internal Server Error

  /users/leaders:
     get:
      tags:
      - user
      summary: "Get all users with their scores."
      description: ""
      operationId: leaders
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
      - name: body
        in: body
        description: Pagination params.
        required: true
        schema:
          $ref: "#/definitions/Pagination"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Leaderboard"
        500:
          description: Internal Server Error

  /session:
    post:
      tags:
      - session
      summary: "Log in into an existing account."
      description: ""
      operationId: loginUser
      consumes:
        - "multipart/form-data"
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: "User credentials."
          required: true
          schema:
            $ref: "#/definitions/UserCredentials"
      responses:
        200:
          description: OK
        401:
          description: Unauthorized
          schema:
            $ref: "#/definitions/ForbiddenRequest"
        500:
          description: Internal Server Error
    delete:
      tags:
      - session
      summary: "Log out from the current account."
      description: ""
      operationId: logoutUser
      consumes: []
      responses:
        200:
          description: OK
        500:
          description: Internal Server Error

definitions:
  ForbiddenRequest:
    type: object
    properties:
      reason:
        type: string
        example: <reason>

  Pagination:
    type: object
    required:
      - page
      - count
    properties:
      page:
        type: integer
        minimum: 0
        example: 0
      count:
        type: integer
        minimum: 0
        example: 5

  UserScore:
    type: object
    required:
      - username
      - score
    properties:
      username:
        type: string
        example: <username>
      score:
        type: integer
        example: 0

  Leaderboard:
    type: object
    properties:
      users:
        type: array
        items:
          $ref: "#/definitions/UserScore"
      total:
        type: integer
        minimum: 0
        example: 0

  UserCredentials:
    type: object
    required:
      - "username"
      - "password"
    properties:
      username:
        type: string
        example: florence
      password:
        type: string
        example: pass123

  UserExtended:
    type: object
    properties:
      username:
        type: string
        example: florence
      score:
        type: integer
        example: 21
      avatar:
        type: string
        example: <avatar>

  UserEdit:
    type: object
    properties:
      newUsername:
        type: string
        example: florence
      newPassword:
        type: string
        example: 21
      newAvatar:
        type: string
example: <avatar>