jerzyn/swagger-demo.yaml

## swagger-demo.yaml
swagger: '2.0'
info:
  version: '1.0.0'
  title: "Wishlist API"
  description: |

    ## Affordances
    This API affords the following actions:
    - Retrieve a list of products
    - Retrieve a single product
    - Create a product
    - Update an existing product (status...)
    - Retrieve reviews about a product
    - Add a product review
    - Create a user
    - Retrieve user profile
    - Retrieve the user wishlist
    - Add a product into the wishlist
    - Delete a specific product from the wishlist
    - Clear the wishlist


produces:
  - application/hal+json      # Representation message format
  - application/problem+json  # Error message format

schemes:
  - https

securityDefinitions:
  oauth2:
    type: oauth2
    authorizationUrl: 'http://example/oauth'
    description: |

      There are three available roles in the application:

        - Anonymous -> can log in, log out, see products, see general ratings from a product.
        - User -> all from Anonymous + following scopes: write:wishlist, read:reviews, write:reviews.
        - Admin -> all from Anonymous + following scopes: write:products, read:reviews, read:reviews:stats, read:users, write:users.
    flow: implicit
    scopes:
      'read:products': read all products
      'write:products': modify products
      'write:wishlist': modify your wishlist
      'read:wishlist': read your wishlist
      'read:reviews': read all reviews
      'write:reviews': write reviews
      'read:reviews:stats': read review statistics
      'read:users': read users
      'write:users': modify users

paths:
  /:
    x-summary: Wishlist

    get:
      summary: API Root
      description: Retrieve the API Root

      responses:
        200:
          description: The root of the API
          schema:
            $ref: '#/definitions/halRoot'


  /products:
    x-summary: List of Products

    get:
      summary: List of Products
      description: Retrieve the whole list of products
      parameters:
        - 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'
        - name: limit
          in: query
          description: The maximum number of reusults to return
          required: false
          type: string
          default: '10'
          x-example: '5'
        - 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
        - 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
        - name: category
          in: query
          description: Category to filter by. Retrieved products must match given category.
          required: false
          type: number
      responses:
        200:
          description: The list of Products
          schema:
            $ref: '#/definitions/halProducts'
      security:
        - oauth2:
          - 'read:products'

    post:
      summary: New Product
      description: Create a new product
      consumes:
        - application/json
      parameters:
        - name: Product
          in: body
          description: Product to be created
          required: true
          schema:
            $ref: '#/definitions/product'
      responses:
        201:
          description: Newly created product
          schema:
            $ref: '#/definitions/halProduct'
      security:
        - oauth2:
          - 'write:products'

  /products/{product_id}:
    x-summary: Product

    parameters:
      - name: product_id
        in: path
        description: Id of the Product
        required: true
        type: string
        x-example: 'DB1124'

    get:
      summary: Get Product
      description: Retrieve product details
      responses:
        200:
          description: A particular Product
          schema:
            $ref: '#/definitions/halProduct'
        404:
          description: The requested Product wasn't found
          headers:
            Content-Type:
              type: string
              default: application/problem+json
          schema:
            $ref: '#/definitions/productNotFound'
      security:
        - oauth2:
          - 'read:products'

    patch:
      summary: Update Product
      description: Update product details
      consumes:
        - application/json
      parameters:
        - name: Product
          in: body
          description: Partial Product update
          required: true
          schema:
            $ref: '#/definitions/productPatch'
      responses:
        200:
          description: The Product was updated
          schema:
            $ref: '#/definitions/halProduct'
      security:
        - oauth2:
          - 'write:products'

  /products/{product_id}/reviews:

    x-summary: List of Product Reviews

    parameters:
      - name: product_id
        in: path
        description: Id of the Product
        required: true
        type: string
        x-example: 'DB1124'

    get:
      summary: List product reviews
      description: Retrieve a list of product reviews
      parameters:
        - 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'
        - name: limit
          in: query
          description: The maximum number of reusults to return
          required: false
          type: string
          default: '10'
          x-example: '5'
      responses:
        200:
          description: The list of Product review
          schema:
            $ref: '#/definitions/halReviews'
      security:
        - oauth2:
          - 'read:reviews'

    post:
      summary: Create product review
      description: Create a new product review
      consumes:
        - application/json
      parameters:
        - name: Review
          in: body
          description: Review to be created
          required: true
          schema:
            $ref: '#/definitions/review'
      responses:
        201:
          description: Newly created product
          schema:
            $ref: '#/definitions/halReview'
      security:
        - oauth2:
          - 'write:reviews'

  /products/{product_id}/reviews-stats:

    x-summary: List of Product Reviews Stats

    parameters:
      - name: product_id
        in: path
        description: Id of the Product
        required: true
        type: string
        x-example: 'DB1124'

    get:
      summary: List product reviews stats
      description: Retrieve a list of product reviews statistics
      parameters:
        - 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'
        - name: limit
          in: query
          description: The maximum number of reusults to return
          required: false
          type: string
          default: '10'
          x-example: '5'
        - name: granularity
          in: query
          type: string
          enum:
            - years
            - months
            - days
          default: months
      responses:
        200:
          description: The list of Product review
          schema:
            $ref: '#/definitions/halReviewsStats'
      security:
        - oauth2:
          - 'read:reviews:stats'

  /users:
    x-summary: Users

    post:
      summary: New user
      description: Create a new user
      consumes:
        - application/json
      parameters:
        - name: User
          in: body
          description: User to be created
          required: true
          schema:
            $ref: '#/definitions/user'
      responses:
        201:
          description: Newly created user
          schema:
            $ref: '#/definitions/halUser'
      security:
        - oauth2:
          - 'write:users'

  /users/{user_id}:
    x-summary: User Profile

    parameters:
      - name: user_id
        in: path
        description: Id of the User
        required: true
        type: string
        x-example: 'xxxxx'

    get:
      summary: User Profile
      description: Retrieve user profile details
      responses:
        200:
          description: A particular User Profile
          schema:
            $ref: '#/definitions/halUser'
      security:
        - oauth2:
          - 'read:users'

  /users/{user_id}/wishlist:
    x-summary: User Wishlist

    parameters:
      - name: user_id
        in: path
        description: Id of the User
        required: true
        type: string
        x-example: '32312'

    get:
      summary: User Wishlist
      description: Retrieve user wishlist
      responses:
        200:
          description: A particular User Wishlist
          schema:
            $ref: '#/definitions/halWishlist'
      security:
        - oauth2:
          - 'read:wishlist'

    delete:
      summary: Clear user wishlist
      description: Clear all the products from user wishlist
      responses:
        204:
          description: Wishlist cleared
      security:
        - oauth2:
          - 'write:wishlist'

  /users/{user_id}/wishlist/{product_id}:
    x-summary: User Product Wishlist

    parameters:
      - name: user_id
        in: path
        description: Id of the User
        required: true
        type: string
        x-example: '32312'

      - name: product_id
        in: path
        description: Id of the Product
        required: true
        type: string
        x-example: 'DB1124'

    post:
      summary: Add product to the wishlist
      description: Add a product to user wishlist
      consumes:
        - application/json
      parameters:
        - name: Wishlist
          in: body
          description: Wishlist to be added
          required: true
          schema:
            $ref: '#/definitions/wishProduct'
      responses:
        201:
          description: Newly add Wishlist
          schema:
            $ref: '#/definitions/halWishProduct'
      security:
      - oauth2:
        - 'write:wishlist'

    delete:
      summary: Delete a product from the wishlist
      description: Delete a product from user wishlist
      responses:
        204:
          description: Wishlist cleared
      security:
        - oauth2:
          - 'write:wishlist'

definitions:
  #
  # API Root
  #
  halRoot:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /
        products:
          href: /products
        product:
          href: /products/{product_id}
        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

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

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

        edit:
          href: /products/DB1124

        delete:
          href: /products/DB1124
      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'
    example:
      status: 'out'

  # Product
  product:
    type: object
    properties:
      id:
        type: string
      title:
        type: string
      description:
        type: string
      category:
        type: string
      status:
        type: string
        enum:
        - available
        - pending
        - sold
        - out
        default: available
      images:
        type: string
      tags:
        type: array
        items:
          type: string
      createdAt:
        type: string
    required:
      - title
      - description
      - category
    example:
      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'


  # 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'
    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:
      id:
        type: string
      comment:
        type: string
      rating:
        type: number
      createdAt:
        type: string
    required:
      - comment
      - rating
    example:
      id: 'DB1124'
      comment: 'This is a review comment example'
      rating: 4.3
      createdAt: '2017-06-21T14:07:17Z'


#
  # 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'
    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
      createdAt:
        type: string
        readOnly: true
    required:
      - comment
      - rating
    example:
      id: 'DB1124'
      comment: 'This is a review comment example'
      rating: 4.3
      createdAt: '2017-06-21T14:07:17Z'

#
  # User Resource
  #

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


  # Review
  user:
    type: object
    properties:
      id:
        type: string
      username:
        type: string
      password:
        type: string
      createdAt:
        type: string
    required:
      - username
      - password
    example:
      id: '232333'
      username: 'Sam'
      createdAt: '2017-06-21T14:07:17Z'

  # 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

        create:
          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

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

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


  # Review
  wishProduct:
    type: object
    properties:
      id:
        type: string
      createdAt:
        type: string
        readOnly: true
    required:
      - id
    example:
      id: 'DB1124'
      createdAt: '2017-06-21T14:07:17Z'


  #
  # -- 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'
	swagger: '2.0'
	info:
	version: '1.0.0'
	title: "Wishlist API"
	description: \|

	## Affordances
	This API affords the following actions:
	- Retrieve a list of products
	- Retrieve a single product
	- Create a product
	- Update an existing product (status...)
	- Retrieve reviews about a product
	- Add a product review
	- Create a user
	- Retrieve user profile
	- Retrieve the user wishlist
	- Add a product into the wishlist
	- Delete a specific product from the wishlist
	- Clear the wishlist


	produces:
	- application/hal+json # Representation message format
	- application/problem+json # Error message format

	schemes:
	- https

	securityDefinitions:
	oauth2:
	type: oauth2
	authorizationUrl: 'http://example/oauth'
	description: \|

	There are three available roles in the application:

	- Anonymous -> can log in, log out, see products, see general ratings from a product.
	- User -> all from Anonymous + following scopes: write:wishlist, read:reviews, write:reviews.
	- Admin -> all from Anonymous + following scopes: write:products, read:reviews, read:reviews:stats, read:users, write:users.
	flow: implicit
	scopes:
	'read:products': read all products
	'write:products': modify products
	'write:wishlist': modify your wishlist
	'read:wishlist': read your wishlist
	'read:reviews': read all reviews
	'write:reviews': write reviews
	'read:reviews:stats': read review statistics
	'read:users': read users
	'write:users': modify users

	paths:
	/:
	x-summary: Wishlist

	get:
	summary: API Root
	description: Retrieve the API Root

	responses:
	200:
	description: The root of the API
	schema:
	$ref: '#/definitions/halRoot'


	/products:
	x-summary: List of Products

	get:
	summary: List of Products
	description: Retrieve the whole list of products
	parameters:
	- 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'
	- name: limit
	in: query
	description: The maximum number of reusults to return
	required: false
	type: string
	default: '10'
	x-example: '5'
	- 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
	- 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
	- name: category
	in: query
	description: Category to filter by. Retrieved products must match given category.
	required: false
	type: number
	responses:
	200:
	description: The list of Products
	schema:
	$ref: '#/definitions/halProducts'
	security:
	- oauth2:
	- 'read:products'

	post:
	summary: New Product
	description: Create a new product
	consumes:
	- application/json
	parameters:
	- name: Product
	in: body
	description: Product to be created
	required: true
	schema:
	$ref: '#/definitions/product'
	responses:
	201:
	description: Newly created product
	schema:
	$ref: '#/definitions/halProduct'
	security:
	- oauth2:
	- 'write:products'

	/products/{product_id}:
	x-summary: Product

	parameters:
	- name: product_id
	in: path
	description: Id of the Product
	required: true
	type: string
	x-example: 'DB1124'

	get:
	summary: Get Product
	description: Retrieve product details
	responses:
	200:
	description: A particular Product
	schema:
	$ref: '#/definitions/halProduct'
	404:
	description: The requested Product wasn't found
	headers:
	Content-Type:
	type: string
	default: application/problem+json
	schema:
	$ref: '#/definitions/productNotFound'
	security:
	- oauth2:
	- 'read:products'

	patch:
	summary: Update Product
	description: Update product details
	consumes:
	- application/json
	parameters:
	- name: Product
	in: body
	description: Partial Product update
	required: true
	schema:
	$ref: '#/definitions/productPatch'
	responses:
	200:
	description: The Product was updated
	schema:
	$ref: '#/definitions/halProduct'
	security:
	- oauth2:
	- 'write:products'

	/products/{product_id}/reviews:

	x-summary: List of Product Reviews

	parameters:
	- name: product_id
	in: path
	description: Id of the Product
	required: true
	type: string
	x-example: 'DB1124'

	get:
	summary: List product reviews
	description: Retrieve a list of product reviews
	parameters:
	- 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'
	- name: limit
	in: query
	description: The maximum number of reusults to return
	required: false
	type: string
	default: '10'
	x-example: '5'
	responses:
	200:
	description: The list of Product review
	schema:
	$ref: '#/definitions/halReviews'
	security:
	- oauth2:
	- 'read:reviews'

	post:
	summary: Create product review
	description: Create a new product review
	consumes:
	- application/json
	parameters:
	- name: Review
	in: body
	description: Review to be created
	required: true
	schema:
	$ref: '#/definitions/review'
	responses:
	201:
	description: Newly created product
	schema:
	$ref: '#/definitions/halReview'
	security:
	- oauth2:
	- 'write:reviews'

	/products/{product_id}/reviews-stats:

	x-summary: List of Product Reviews Stats

	parameters:
	- name: product_id
	in: path
	description: Id of the Product
	required: true
	type: string
	x-example: 'DB1124'

	get:
	summary: List product reviews stats
	description: Retrieve a list of product reviews statistics
	parameters:
	- 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'
	- name: limit
	in: query
	description: The maximum number of reusults to return
	required: false
	type: string
	default: '10'
	x-example: '5'
	- name: granularity
	in: query
	type: string
	enum:
	- years
	- months
	- days
	default: months
	responses:
	200:
	description: The list of Product review
	schema:
	$ref: '#/definitions/halReviewsStats'
	security:
	- oauth2:
	- 'read:reviews:stats'

	/users:
	x-summary: Users

	post:
	summary: New user
	description: Create a new user
	consumes:
	- application/json
	parameters:
	- name: User
	in: body
	description: User to be created
	required: true
	schema:
	$ref: '#/definitions/user'
	responses:
	201:
	description: Newly created user
	schema:
	$ref: '#/definitions/halUser'
	security:
	- oauth2:
	- 'write:users'

	/users/{user_id}:
	x-summary: User Profile

	parameters:
	- name: user_id
	in: path
	description: Id of the User
	required: true
	type: string
	x-example: 'xxxxx'

	get:
	summary: User Profile
	description: Retrieve user profile details
	responses:
	200:
	description: A particular User Profile
	schema:
	$ref: '#/definitions/halUser'
	security:
	- oauth2:
	- 'read:users'

	/users/{user_id}/wishlist:
	x-summary: User Wishlist

	parameters:
	- name: user_id
	in: path
	description: Id of the User
	required: true
	type: string
	x-example: '32312'

	get:
	summary: User Wishlist
	description: Retrieve user wishlist
	responses:
	200:
	description: A particular User Wishlist
	schema:
	$ref: '#/definitions/halWishlist'
	security:
	- oauth2:
	- 'read:wishlist'

	delete:
	summary: Clear user wishlist
	description: Clear all the products from user wishlist
	responses:
	204:
	description: Wishlist cleared
	security:
	- oauth2:
	- 'write:wishlist'

	/users/{user_id}/wishlist/{product_id}:
	x-summary: User Product Wishlist

	parameters:
	- name: user_id
	in: path
	description: Id of the User
	required: true
	type: string
	x-example: '32312'

	- name: product_id
	in: path
	description: Id of the Product
	required: true
	type: string
	x-example: 'DB1124'

	post:
	summary: Add product to the wishlist
	description: Add a product to user wishlist
	consumes:
	- application/json
	parameters:
	- name: Wishlist
	in: body
	description: Wishlist to be added
	required: true
	schema:
	$ref: '#/definitions/wishProduct'
	responses:
	201:
	description: Newly add Wishlist
	schema:
	$ref: '#/definitions/halWishProduct'
	security:
	- oauth2:
	- 'write:wishlist'

	delete:
	summary: Delete a product from the wishlist
	description: Delete a product from user wishlist
	responses:
	204:
	description: Wishlist cleared
	security:
	- oauth2:
	- 'write:wishlist'

	definitions:
	#
	# API Root
	#
	halRoot:
	type: object
	allOf:
	- $ref: '#/definitions/halResource'
	example:
	_links:
	self:
	href: /
	products:
	href: /products
	product:
	href: /products/{product_id}
	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

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

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

	edit:
	href: /products/DB1124

	delete:
	href: /products/DB1124
	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'
	example:
	status: 'out'

	# Product
	product:
	type: object
	properties:
	id:
	type: string
	title:
	type: string
	description:
	type: string
	category:
	type: string
	status:
	type: string
	enum:
	- available
	- pending
	- sold
	- out
	default: available
	images:
	type: string
	tags:
	type: array
	items:
	type: string
	createdAt:
	type: string
	required:
	- title
	- description
	- category
	example:
	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'


	# 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'
	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:
	id:
	type: string
	comment:
	type: string
	rating:
	type: number
	createdAt:
	type: string
	required:
	- comment
	- rating
	example:
	id: 'DB1124'
	comment: 'This is a review comment example'
	rating: 4.3
	createdAt: '2017-06-21T14:07:17Z'




	#
	# 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'
	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
	createdAt:
	type: string
	readOnly: true
	required:
	- comment
	- rating
	example:
	id: 'DB1124'
	comment: 'This is a review comment example'
	rating: 4.3
	createdAt: '2017-06-21T14:07:17Z'

	#
	# User Resource
	#

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


	# Review
	user:
	type: object
	properties:
	id:
	type: string
	username:
	type: string
	password:
	type: string
	createdAt:
	type: string
	required:
	- username
	- password
	example:
	id: '232333'
	username: 'Sam'
	createdAt: '2017-06-21T14:07:17Z'

	# 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

	create:
	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

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

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


	# Review
	wishProduct:
	type: object
	properties:
	id:
	type: string
	createdAt:
	type: string
	readOnly: true
	required:
	- id
	example:
	id: 'DB1124'
	createdAt: '2017-06-21T14:07:17Z'


	#
	# -- 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'