swagger.yaml

openapi: 3.0.0
info:
  version: '2.0'
  title: 'HomeCheck'
  description: UNITN - Ingegneria del software 2 project
  license:
    name: MIT
    url: https://github.com/apiaryio/polls-api/blob/master/LICENSE
servers:
  - url: http://homecheck-api.herokuapp.com/v2/
    description: Production server (uses live data)
  - url: http://localhost:3000/v2
    description: Local server (demo on local host)

security:
  - bearerAuth: []
paths:
  /users/login:
    summary: Login
    post:
      security: []
      summary: Send login data
      tags:
        - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginForm'
      responses:
        '200':
          description: Logged in correctly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginRes'
        '401':
          description: User not logged in correctly
  /users/register:
    summary: Register
    post:
      security: []
      summary: Send register data
      tags:
        - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterForm'
      responses:
        '200':
          description: Register successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterRes'
  /users/confirm/{token}:
    summary: Confirmation
    get:
      security: []
      summary: Confirm account
      tags:
        - Users
      responses:
        '201':
          description: Confirmation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterRes'
        '400':
          description: Token missing
        '404':
          description: Token not found
        '500':
          description: Error in confirmation
  /users/passwordReset:
    summary: Reset Password
    post:
      security: []
      summary: Send a new password to user's email
      tags:
        - Users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'Email of the user'
      responses:
        '200':
          description: 'New password sent'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResetRes'
        '404':
          description: 'Cannot find a user with the requested email.'
        '500':
          description: 'Something went wrong during reset password.'
  /users/password:
    summary: Password
    patch:
      summary: Update Password
      tags:
        - Users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                oldPassword:
                  type: string
                  description: 'Old password of the user'
                newPassword:
                  type: string
                  description: 'New password of the user'
                confirmPassword:
                  type: string
                  description: 'Confirm of new password of the user'
      responses:
        '200':
          description: 'Update password successful'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordUpdateRes'
        '400':
          description: 'Data not correctly provided'
        '500':
          description: 'Something went wrong during update password.'
  /products:
    summary: Products Collection
    get:
      summary: Get list of products
      tags:
        - Products
      responses:
        '200':
          description: 'Successful response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfProductsRes'
        '401':
          description: 'User not logged in'
    post:
      summary: Insert a new product
      tags:
        - Products
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Name of the product'
                quantity:
                  type: 'integer'
                  description: 'Product quantity'
                expiryDate:
                  type: string
                  description: 'Expiry date of product'
                category:
                  type: string
                  description: 'Category id of product'
                group:
                  type: string
                  description: 'Group id of product'
      responses:
        '200':
          description: 'Successful insert'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductRes'
        '401':
          description: 'User not logged in'
        '403':
          description: 'Not authorized to do this action'
  /products/{productId}:
    summary: Product
    parameters:
      - name: 'productId'
        in: 'path'
        description: 'Id of the product'
        required: true
    get:
      summary: Get product by id
      tags:
        - Products
      responses:
        '200':
          description: 'Successful response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductRes'
              examples:
                1:
                  value:
                    data:
                      message: 'Get product successful'
                      product:
                        id: '1'
                        name: 'Tomato Sauce'
                        quantity: 7
                        expiryDate: 25/12/2020
                        category:
                          id: '1'
                          name: 'Sauce'
                          icon: '/path/to/ico.jpg'
                        group:
                          id: '1'
                          name: 'Pantry'
                        request:
                          type: 'GET'
                          url: http://homecheck-api.herokuapp.com/v2/products/1
        '401':
          description: 'User not logged in'
    put:
      summary: Update a product info
      tags:
        - Products
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Name of the product'
                quantity:
                  type: 'integer'
                  description: 'Product quantity'
                expiryDate:
                  type: string
                  description: 'Expiry date of product'
                category:
                  type: string
                  description: 'Category id of product'
                group:
                  type: string
                  description: 'Group id of product'
      responses:
        '200':
          description: 'Successful update'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductRes'
        '401':
          description: 'User not logged in'
        '403':
          description: 'Not authorized to do this action'
    delete:
      summary: Delete a product
      tags:
        - Products
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductRes'
        '401':
          description: User not logged in
        '403':
          description: Not authorized to do this action
  /categories:
    summary: Categories Collection
    get:
      summary: Get list of categories
      tags:
        - Categories
      responses:
        '200':
          description: Get categories successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfCategoriesRes'
        '400':
          description: No category provided
        '401':
          description: Authentication failed.
        '500':
          description: Something went wrong when retrieving categories.
    post:
      summary: Insert a new category
      tags:
        - Categories
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Name of the category'
                icon:
                  type: string
                  description: 'Path of the category icon'
      responses:
        '201':
          description: Creation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: Name or icon are not filled in with the corresponding data.
        '401':
          description: Authentication failed.
        '409':
          description: Category already exists.
        '500':
          description: Something went wrong during creation.
  /categories/{categoryId}:
    summary: Category
    parameters:
      - name: 'categoryId'
        in: 'path'
        description: 'Id of the category'
        required: true
    get:
      summary: Get category by id
      tags:
        - Categories
      responses:
        '200':
          description: Get category successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                1:
                  value:
                    data:
                      message: 'Get category successful'
                      category:
                        id: '1'
                        name: 'Bread'
                        icon: '/path/to/icon.jpg'
                        default: false
                        request:
                          type: 'GET'
                          url: http://homecheck-api.herokuapp.com/v2/categories/1
        '400':
          description: No category provided
        '401':
          description: Authentication failed
        '403':
          description: User not authorized to get category
        '404':
          description: Category not found
        '500':
          description: Something went wrong when retrieving category
    put:
      summary: Update category info
      tags:
        - Categories
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Name of the category'
                icon:
                  type: string
                  description: 'Path of the category icon'
      responses:
        '200':
          description: 'Update successful'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          description: 'User not logged in'
        '403':
          description: 'Not authorized to do this action'
        '404':
          description: 'Category not found'
    delete:
      summary: Delete a category
      tags:
        - Categories
      responses:
        '200':
          description: Deletion successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: No category provided
        '401':
          description: Authentication failed
        '403':
          description: User not authorized to delete category
        '404':
          description: Category not found
        '500':
          description: Something went wrong during deletion
  /groups:
    summary: Groups Collection
    get:
      summary: Get list of groups
      tags:
        - Groups
      responses:
        '200':
          description: Get groups successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfGroupsRes'
        '401':
          description: Authentication failed.
        '500':
          description: Something went wrong when retrieving groups.
  /groups/{groupId}:
    summary: Group
    parameters:
      - name: 'groupId'
        in: 'path'
        description: 'Id of the group'
        required: true
    get:
      summary: Get group by id
      tags:
        - Groups
      responses:
        '200':
          description: Get group successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRes'
        '400':
          description: No group provided
        '401':
          description: Authentication failed
        '404':
          description: Group not found
        '500':
          description: Something went wrong when retrieving group
  /sharing-links/token:
    summary: Food storage shared token
    get:
      summary: Get shared token
      tags:
        - Sharing
      responses:
        '200':
          description: 'Successful response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharingLinkToken'
        '401':
          description: 'User not logged in'
        '404':
          description: 'Token not found'
    post:
      summary: Generate a new token
      tags:
        - Sharing
      responses:
        '200':
          description: 'Successful insert'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharingLinkToken'
        '401':
          description: 'User not logged in'
        '409':
          description: 'Token already exists'
    delete:
      summary: Delete/revoke current token
      tags:
        - Sharing
      responses:
        '200':
          description: 'Successful response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharingLinkToken'
        '401':
          description: 'User not logged in'
        '403':
          description: 'Not authorized to do this action'
  /sharing-links/{token}/products:
    summary: 'Shared products collection'
    parameters:
      - name: 'token'
        in: 'path'
        description: 'Token generated by the owner of the product'
        required: true
    get:
      security: []
      summary: 'Get list of shared products'
      tags:
        - Sharing
      responses:
        '200':
          description: 'Successful response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfProductsRes'
        '403':
          description: 'User not authorized'
  /sharing-links/{token}/products/{productId}:
    summary: 'Shared product'
    parameters:
      - name: 'productId'
        in: 'path'
        description: 'Id of the product'
        required: true
      - name: 'token'
        in: 'path'
        description: 'Token generated by the owner of the product'
        required: true
    get:
      summary: Get shared product by id
      security: []
      tags:
        - Sharing
      responses:
        '200':
          description: 'Successful response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductRes'
        '403':
          description: 'User not authorized'
        '404':
          description: 'Product not found'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    LoginForm:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          description: 'Email address of the user'
        password:
          type: string
          description: 'Password of the user'
    RegisterForm:
      type: object
      required:
        - email
        - password
        - firstname
        - lastname
      properties:
        email:
          type: string
          description: 'Email address of the user'
        password:
          type: string
          description: 'Password of the user'
        firstname:
          type: string
          description: 'Firstname of the user'
        lastname:
          type: string
          description: 'Lastname of the user'
    LoginRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: Authentication successful
            token:
              type: string
              description: 'JWT Authentication token'
            user:
              $ref: '#/components/schemas/UserRes'
    RegisterRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Registration successful! Please, check your email to confirm your user.'
            user:
              $ref: '#/components/schemas/UserRes'
    ConfirmRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Confirmation successful.'
            user:
              $ref: '#/components/schemas/UserRes'
    PasswordResetRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'New password sent'
            user:
              $ref: '#/components/schemas/UserRes'
    PasswordUpdateRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Update password successful'
            user:
              $ref: '#/components/schemas/UserRes'
    UserRes:
      type: object
      required:
        - id
        - email
        - firstname
        - lastname
      properties:
        id:
          type: string
          description: 'Id of the user'
        email:
          type: string
          description: 'Email address of the user'
        firstname:
          type: string
          description: 'Firstname of the user'
        lastname:
          type: string
          description: 'Lastname of the user'
    ProductRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Response status description'
            product:
              type: object
              required:
                - id
                - name
                - quantity
                - expiryDate
                - category
                - group
              properties:
                id:
                  type: string
                  description: 'Id of the product'
                name:
                  type: string
                  description: 'Name of the product'
                quantity:
                  type: 'integer'
                  description: 'Product quantity'
                expiryDate:
                  type: string
                  description: 'Expiry date of product'
                category:
                  type: object
                  properties:
                    id:
                      type: string
                      description: 'Id of the category'
                    name:
                      type: string
                      description: 'Name of the category'
                    icon:
                      type: string
                      description: 'Path of the category icon'
                group:
                  type: object
                  properties:
                    id:
                      type: string
                      description: 'Id of the group'
                    name:
                      type: string
                      description: 'Name of the group'
                request:
                  type: object
                  properties:
                    type:
                      type: string
                      description: 'Request method'
                    url:
                      type: string
                      description: 'Request url'
    ArrayOfProductsRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Response status description'
            products:
              type: array
              items:
                type: object
                required:
                  - id
                  - name
                  - quantity
                  - expiryDate
                  - category
                  - group
                properties:
                  id:
                    type: string
                    description: 'Id of the product'
                  name:
                    type: string
                    description: 'Name of the product'
                  quantity:
                    type: 'integer'
                    description: 'Product quantity'
                  expiryDate:
                    type: string
                    description: 'Expiry date of product'
                  category:
                    type: object
                    properties:
                      id:
                        type: string
                        description: 'Id of the category'
                      name:
                        type: string
                        description: 'Name of the category'
                      icon:
                        type: string
                        description: 'Path of the category icon'
                  group:
                    type: object
                    properties:
                      id:
                        type: string
                        description: 'Id of the group'
                      name:
                        type: string
                        description: 'Name of the group'
    Category:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: Get category successful
            category:
              type: object
              properties:
                id:
                  type: string
                  description: 'Id of the category'
                name:
                  type: string
                  description: 'Name of the category'
                icon:
                  type: string
                  description: 'Path of the category icon'
                default:
                  type: boolean
                  description: 'Whether is a default category or not'
                user:
                  type: string
                  description: 'Id of the user to whom this category belongs'
                request:
                  type: object
                  properties:
                    type:
                      type: string
                      description: 'Request method'
                    url:
                      type: string
                      description: 'Request url'
    ArrayOfCategoriesRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Get categories successful.'
            categories:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: 'Id of the category'
                  name:
                    type: string
                    description: 'Name of the category'
                  icon:
                    type: string
                    description: 'Path of the category icon'
                  default:
                    type: boolean
                    description: 'Whether is a default category or not'
                  user:
                    type: string
                    description: 'Id of the user to whom this category belongs'
                  request:
                    type: object
                    properties:
                      type:
                        type: string
                        description: 'Request method'
                      url:
                        type: string
                        description: 'Request url'
    GroupRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Get groups successful.'
            group:
              type: object
              properties:
                id:
                  type: string
                  description: 'Id of the group'
                name:
                  type: string
                  description: 'Name of the group'
                request:
                  type: object
                  properties:
                    type:
                      type: string
                      description: 'Request method'
                    url:
                      type: string
                      description: 'Request url'
    ArrayOfGroupsRes:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              description: 'Get groups successful.'
            groups:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: 'Id of the group'
                  name:
                    type: string
                    description: 'Name of the group'
                  request:
                    type: object
                    properties:
                      type:
                        type: string
                        description: 'Request method'
                      url:
                        type: string
                        description: 'Request url'

    SharingLinkToken:
      type: object
      properties:
        data:
          type: object
          required:
            - sharingLinks
          properties:
            message:
              type: string
              description: 'Response status description'
            sharingLinks:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                  description: 'Sharing token'
                request:
                  type: object
                  properties:
                    type:
                      type: string
                      description: 'Request method'
                    url:
                      type: string
                      description: 'Request url'