sample-api-models.yaml

### Domains, a place to put your reusable components

### Examples...

info:
  description: This is a Domain containing object models for the [Onboarding] Wishlist API
  version: '1.0.0'
  title: Wishlist Object Models

definitions:

# TODO - Create a definition of the product object model
  # Product
  # product:
    # type: 
    #properties:
    # NOTE: product will have a title, description, category, status, image, tags. Of those title, description and category are required parameters. Status can have a value of available, pending, sold or out and available is the default one. Tags is an array of strings. Please, add an example as well (you can start from the example and then define the model)
    # example:

  #
  # API Root
  #
  halRoot:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /
        products:
          href: /products
        users:
          href: /users

  #
  # Product Resource
  #
  halProducts:
    type: object
    properties:
      productCount:
        type: number
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /products

        create:
          href: /products

        next:
          href: /products?offset=5&limit=5

        first:
          href: /products?offset=0&limit=5

        last:
          href: /products?offset=40&limit=5
        
        productDetail:
          href: /products/{product_id}

      _embedded:
        product:
          - $ref: '#/definitions/halProduct/example'

  # Product HAL Wrapper
  halProduct:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/product'
    properties:
      id:
        type: string
      createdAt:
        type: string
    example:
      _links:
        self:
          href: /products/DB1124

        edit:
          href: /products/DB1124

        delete:
          href: /products/DB1124
        
        productReviews:
          href: /products/DB1124/reviews
          
        productReviewsStats:
          href: /products/DB1124/reviews-stats
      id: 'DB1124'
      title: 'My Product title'
      description : 'An example of a product description'
      category: 'lorem'
      status: 'available'
      image: 'https://cdn.sportsshoes.com/product/A/ADI8522/ADI8522_200_1.jpg'
      tags: ['beyond', 'zapitilla', 'zaragoza']
      createdAt: '2017-06-21T14:07:17Z'


  # Partial Product
  productPatch:
    type: object
    allOf:
      - $ref: '#/definitions/product'
    properties:
      id:
        type: string
    example:
      status: 'out'

  # Product Not Found Error
  productNotFound:
    type: object
    allOf:
      - $ref: '#/definitions/problemDetail'
    example:
      title: 'Not Found'
      detail: 'Cannot find the requested product'
      status: 404
      instance: '/products/DB1124'


  #
  # Review Resource
  #
  halReviews:
    type: object
    properties:
      reviewCount:
        type: number
      averageRating:
        type: number
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /products/{product_id}/reviews
          templated: true

        create:
          href: /products/{product_id}/reviews
          templated: true

        next:
          href: /products/{product_id}/reviews?offset=5&limit=5
          templated: true

        first:
          href: /products/{product_id}/reviews?offset=0&limit=5
          templated: true

        last:
          href: /products/{product_id}/reviews?offset=40&limit=5
          templated: true

      _embedded:
        reviewCount: 122
        averageRating: 4.3
        review:
          - $ref: '#/definitions/halReview/example'

  # HAL Wrapper
  halReview:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/review'
    properties:
      id:
        type: string
      createdAt:
        type: string
    example:
      _links:
        self:
          href: /products/{product_id}/reviews
          templated: true
      id: 'DB1124'
      comment: 'This is a review comment example'
      rating: 4.3
      createdAt: '2017-06-21T14:07:17Z'


  # Review
  review:
    type: object
    properties:
      comment:
        type: string
      rating:
        type: number
    required:
      - comment
      - rating
    example:
      comment: 'This is a review comment example'
      rating: 4.3

#
  # Review Stats Resource
  #
  halReviewsStats:
    type: object
    properties:
      reviewCount:
        type: number
      averageRating:
        type: number
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /products/{product_id}/reviews-stats
          templated: true

        next:
          href: /products/{product_id}/reviews-stats?offset=5&limit=5
          templated: true

        first:
          href: /products/{product_id}/reviews-stats?offset=0&limit=5
          templated: true

        last:
          href: /products/{product_id}/reviews-stats?offset=40&limit=5
          templated: true

      _embedded:
        reviewCount: 122
        averageRating: 4.3
        history:
          - $ref: '#/definitions/halReviewStatsItem'


  # HAL Wrapper
  halReviewStatsItem:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/reviewStatsItem'
    properties:
      createdAt:
        type: string
        readOnly: true
    example:
      date: '2017-06-21T14:07:17Z'
      rating: 4.3


  # Review Stats
  reviewStatsItem:
    type: object
    properties:
      id:
        type: string
      comment:
        type: string
      rating:
        type: number
    required:
      - comment
      - rating
    example:
      comment: 'This is a review comment example'
      rating: 4.3

#
  # User Resource
  #

  # HAL Wrapper
  halUser:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/user'
    properties:
      id:
        type: string
      createdAt:
        type: string
    example:
      _links:
        self:
          href: /users/{user_id}
          templated: true
        wishlist:
          href: /users/{user_id}/wishlist
      id: '232333'
      username: 'Sam'
      createdAt: '2017-06-21T14:07:17Z'


  # Review
  user:
    type: object
    properties:
      username:
        type: string
      password:
        type: string
    required:
      - username
      - password
    example:
      username: 'Sam'

  # User Not Found Error
  userNotFound:
    type: object
    allOf:
      - $ref: '#/definitions/problemDetail'
    example:
      title: 'Not Found'
      detail: 'Cannot find any user with this id'
      status: 404
      instance: '/users/{user_id}'


#
  # Review Resource
  #
  halWishlist:
    type: object
    properties:
      wishlistCount:
        type: number
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /users/{user_id}/wishlist
          templated: true

        next:
          href: /users/{user_id}/wishlist?offset=5&limit=5
          templated: true

        first:
          href: /users/{user_id}/wishlist?offset=0&limit=5
          templated: true

        last:
          href: /users/{user_id}/wishlist?offset=40&limit=5
          templated: true
          
        addProduct:
          href: /users/{user_id}/wishlist/{product_id}
          
        removeProduct:
          href: /users/{user_id}/wishlist/{product_id}
          
        delete:
          href: /users/{user_id}/wishlist

      _embedded:
        wishlistCount: 122
        wishlist:
          - $ref: '#/definitions/halWishProduct/example'

  # HAL Wrapper
  halWishProduct:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/wishProduct'
    properties:    
      createdAt:
        type: string
        readOnly: true
    example:
      _links:
        self:
          href: /products/{product_id}
          templated: true
      productId: 'DB1124'
      createdAt: '2017-06-21T14:07:17Z'


  # Review
  wishProduct:
    type: object
    properties:
      productId:
        type: string
    required:
      - productId
    example:
      productId: 'DB1124'


  #
  # -- DO NOT EDIT BEYOND THIS POINT --
  #

  # Media Types Definitions

  #
  # application/problem+json
  #
  problemDetail:
    type: object
    properties:
      type:
        type: string
      title:
        type: string
      status:
        type: number
      detail:
        type: string
      instance:
        type: string
    required:
      - title
      - detail

  #
  # application/hal+json defintion
  #
  halLinkObject:
    type: object
    required:
      - href
    properties:
      href:
        type: string
      templated:
        type: boolean
      type:
        type: string
      deprecation:
        type: string
      name:
        type: string
      profile:
        type: string
      title:
        type: string
      hreflang:
        type: string

  halCuriesLink:
    title: HAL Curies Link
    allOf:
      - type: object
        properties:
          templated:
            enum:
              - true
        required:
          - templated
      - $ref: '#/definitions/halLinkObject'

  halResource:
    title: HAL Resource Object
    type: object
    properties:
      _links:
        type: object
        additionalProperties:
          # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
          allOf:
            - $ref: '#/definitions/halLinkObject'
            - type: array
              items:
                - $ref: '#/definitions/halLinkObject'
        properties:
          curies:
            # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
            allOf:
              - $ref: '#/definitions/halCuriesLink'
              - type: array
                items:
                  - $ref: '#/definitions/halCuriesLink'
      _embedded:
        type: object
        additionalProperties: true
        # WARN: Apiary doesn't support circular references
        # additionalProperties:
        #   anyOf:
        #     - $ref: '#/definitions/hal_resource'
        #     - type: array
        #       items:
        #         - $ref: '#/definitions/hal_resource'

# responses:
#   GeneralError:
#     description: General Error
#     schema:
#       $ref: '#/definitions/ErrorModel'

parameters:
  offsetParam:
    name: offset
    in: query
    description: Number of results to skip from the start of the list
    required: false
    type: string
    default: '0'
    x-example: '10'
    
  limitParam:
    name: limit
    in: query
    description: The maximum number of reusults to return
    required: false
    type: string
    default: '10'
    x-example: '5'
    
  statusParam:
    name: status
    in: query
    description: Statuses to filter by. Retrieved products must match any of the given statuses.
    required: false
    type: array
    items:
      type: string
      enum:
      - available
      - pending
      - sold
      - out
    collectionFormat: csv
    
  tagsParam:
    name: tags
    in: query
    description: Tags to filter by. Retrieved products must match all given tags.
    required: false
    type: array
    items:
      type: number
    collectionFormat: csv
    
  categoryParam:
    name: category
    in: query
    description: Category to filter by. Retrieved products must match given category.
    required: false
    type: number
    
  granularityParam:
    name: granularity
    in: query
    type: string
    enum:
      - years
      - months
      - days
    default: months

# pathitems:
#   EntityOperations:
#     get:
#       description: Returns a pet based on ID
#       summary: Find pet by ID
#       responses:
#         default:
#           $ref: '#/responses/GeneralError'