Stripped-down YML for Jibestream stuff ... DO NOT MERGE, just an example for use with swagger-editor ...

foo,yml

swagger: "2.0"
info:
  version: "1"
  title: Westfield Store Service
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json

# Model / Schema / Response definitions
# -------------------------------------
definitions:
  emptyObject:
    description: Empty object

  genericLink:
    required:
      - href
    properties:
      href:
        description: URL of the link
        type: string

  imageLink:
    required:
      - href
      - ref
    properties:
      href:
        description: Canonical link to the image
        type: string
      ref:
        description: Storage provider ID used to generate the link
        type: string

  retailerLink:
    required:
      - href
    properties:
      href:
        description: Link to the retailer
        type: string

  metaResponse:
    description: Response metadata
    required:
      - api_version
    properties:
      api_version:
        description: API Version
        type: string
        example: "1"
    additionalProperties:
      page:
        description: Current page number
        type: integer
        example: 1
      page_count:
        description: Total number of pages
        type: integer
        example: 10
      per_page:
        description: Number of results per page
        type: integer
        example: 25
      total:
        description: Total number of results for all pages
        type: integer
        example: 100

  # Location parameters
  # ---------------------------------
  location:
    type: object
    description: Jibestream location information
    properties:
      primary:
        type: boolean
        description: Primary level
      location_id:
        type: string
        description: Jibestream location ID
      name:
        type: string
        description: Location description (e.g., "Next to Bloomingdales")
      level_id:
        type: string
        description: Jibestream floor ID
      level_name:
        type: string
        description: Level description (e.g., "Floor 1")

  locations:
    type: object
    description: Jibestream location association ids and metadata
    required:
      - data
    properties:
      data:
        type: array
        items:
          $ref: "#/definitions/location"

  # Retailer parameters and responses
  # ---------------------------------
  retailer:
    description: A retailer that has stores in Westfield centres.
    properties:
      _links:
        $ref: "#/definitions/retailerLinks"
      cam_ref:
        description: Conversion tracking provider ID
        type:
          - string
          - "null"
      campaign_id:
        description: ID of a Westfield campaign for the retailer
        type:
          - string
          - "null"
      category_ids:
        description: List of categories the retailer belongs to
        type: array
        items:
          type: integer
      country:
        description: Two letter code of the country the retailer operates in
        type:
          - string
          - "null"
      currency_code:
        description: Three letter code of the currency the retailer uses
        type: string
      email_address:
        description: E-mail address of the retailer
        type:
          - string
          - "null"
      is_enabled:
        description: Flag indicating if the retailer is enabled in the Westfield system
        type: boolean
      lease_id:
        description: Number of the retailer's lease with Westfield
        type:
          - string
          - "null"
      name:
        description: Name of the retailer
        type: string
      product_tier:
        description: Tiers for grouping similar retailers
        type: integer
        enum:
          - 1
          - 2
          - 3
      product_upload_enabled:
        description: Flag indicating if the retailer can upload products to the Westfield system
        type: boolean
      retailer_code:
        description: URL-friendly code for the retailer
        type: string
      retailer_id:
        description: Auto generated ID
        type: integer
      store_profile:
        description: Long description of the retailer
        type:
          - string
          - "null"
      storefront_ref:
        description: Storage provider ID of the image of a store front of the retailer
        type:
          - string
          - "null"
      updated_at:
        description: Date and time the retailer was last updated.
        type: string
        format: date-time
      url:
        description: URL of the retailer's website
        type:
          - string
          - "null"
    additionalProperties:
      deleted_at:
        type: string
        format: date-time
        description: Date and time the retailer was marked as deleted

  retailerLinks:
    properties:
      self:
        description: Canonical link to retailer
        $ref: '#/definitions/retailerLink'
      logo:
        description: Link to retailer logo
        $ref: '#/definitions/imageLink'

  retailerResponse:
    description: Information about a specific retailer
    required:
      - data
      - errors
      - meta
    properties:
      data:
        $ref: "#/definitions/retailer"
      errors:
        $ref: "#/definitions/emptyObject"
      meta:
        $ref: "#/definitions/metaResponse"

  retailersListResponse:
    description: List of retailers
    required:
      - data
      - errors
      - meta
    properties:
      data:
        type: array
        items:
          $ref: "#/definitions/retailer"
      errors:
        $ref: "#/definitions/emptyObject"
      meta:
        $ref: "#/definitions/metaResponse"

  # Store parameters and responses
  # ---------------------------------
  store:
    description: A store belonging to a retailer in a Westfield centre.
    properties:
      _links:
        $ref: "#/definitions/storeLinks"
      accepts_giftcards:
        description: Flag indicating if the store accepts Westfield gift cards
        type: boolean
      category_ids:
        description: List of categories the store belongs to
        type: array
        items:
          type: integer
      centre_id:
        description: ID of the Westfield centre the store is in
        type: string
      description:
        description: Long description of the store's retailer
        type: string
      dining_cuisine:
        description: Cuisine offered by the store if it provides dining facilities
        type:
          - string
          - "null"
      dining_image_ref:
        description: Storage provider ID of the dining image of the store if it provides dining facilities
        type: string
      dining_price_guide:
        description: Number indicating the relative price of dining at the store
        type:
          - integer
          - "null"
      disabled_date:
        description: Date the store was disabled in the Westfield system
        type:
          - string
          - "null"
        format: date-time
      email_address:
        description: E-mail address of the store
        type:
          - string
          - "null"
      enabled:
        description: Flag indicating if the store is enabled in the Westfield system
        type: boolean
      enabled_date:
        description: Date the store was enabled in the Westfield system
        type:
          - string
          - "null"
        format: date-time
      featured:
        description: Flag indicating if the store is currently being promoted on the website
        type: boolean
      lease_number:
        description: Number of the store's lease with Westfield
        type:
          - string
          - "null"
      locations:
        description: List of Jibestream locations and meta data
        type: array
        items:
          $ref: "#/definitions/location"
      major:
        description: Flag indicating that stores, such as anchor stores, are major in their centre
        type: boolean
      name:
        description: Name of the store
        type: string
      phone_number:
        description: Phone number of the store
        type: string
      products:
        description: Flag indicating if the store's retailer can upload products to the Westfield system
        type: boolean
      retailer_code:
        description: Code of the retailer the store belongs to
        type: string
      retailer_id:
        description: ID of the retailer the store belongs to
        type: integer
      salience:
        description: Numeric value used for wayfinding applications
        type: integer
      shop_number:
        description: The shop number in the Westfield centre the store occupies
        type:
          - string
          - "null"
      store_front_image_ref:
        description: Storage provider ID of the store's store front image
        type: string
      store_id:
        description: Auto generated ID
        type: integer
      updated_at:
        description: Date and time the retailer was last updated.
        type:
          - string
          - "null"
        format: date-time
      url:
        description: URL of the store's website
        type:
          - string
          - "null"
    additionalProperties:
      deleted_at:
        type: string
        format: date-time
        description: Date and time the store was marked as deleted

  storeLinks:
    description: Relevant links for the store
    properties:
      dining:
        description: Links for stores that provide dining facilities
        properties:
          image:
            description: The link to the dining image of the store
            $ref: "#/definitions/imageLink"
          menu:
            description: The link to the menu of the store
            $ref: "#/definitions/genericLink"
      logo:
        description: The link to the logo image of the store's retailer
        $ref: "#/definitions/imageLink"
      self:
        description: The link for details about this store
        $ref: "#/definitions/genericLink"
      store_front:
        description: The link to the store front image of the store
        $ref: "#/definitions/imageLink"

  storeResponse:
    description: Information about a specific store
    required:
      - data
      - errors
      - meta
    properties:
      data:
        $ref: "#/definitions/store"
      errors:
        $ref: "#/definitions/emptyObject"
      meta:
        $ref: "#/definitions/metaResponse"

  storesListResponse:
    description: List of stores
    required:
      - data
      - errors
      - meta
    properties:
      data:
        type: array
        items:
          $ref: "#/definitions/store"
      errors:
        $ref: "#/definitions/emptyObject"
      meta:
        $ref: "#/definitions/metaResponse"

  # Status responses
  # ----------------
  401Error:
    required:
      - access_token
    properties:
      access_token:
        type: array
        items:
          type: string
          description: "Authentication failure message"

  401Response:
    required:
      # - data
      - errors
      # - meta
    properties:
      # data:
      #   $ref: '#/definitions/emptyObject'
      errors:
        $ref: '#/definitions/401Error'
      # meta:
      #   $ref: '#/definitions/metaResponse'

  404Error:
    required:
      - base
    properties:
      base:
        type: array
        items:
          $ref: "#/definitions/404ErrorDetails"

  404ErrorDetails:
    required:
      - message
      - params
    properties:
      message:
        description: Error description
        type: string
      params:
        description: Request parameters supplied
        type: object

  404Response:
    required:
      - data
      - errors
      - meta
    properties:
      data:
        $ref: '#/definitions/emptyObject'
      errors:
        $ref: '#/definitions/404Error'
      meta:
        $ref: '#/definitions/metaResponse'

  406Error:
    required:
      - base
    properties:
      base:
        type: array
        items:
          $ref: '#/definitions/406ErrorDetails'

  406ErrorDetails:
    required:
      - message
      - params
    properties:
      message:
        description: Description of error
        type: string
      params:
        description: parameters
        type: object

  406Response:
    required:
      - data
      - errors
      - meta
    properties:
      data:
        $ref: '#/definitions/emptyObject'
      errors:
        $ref: '#/definitions/406Error'
      meta:
        $ref: '#/definitions/metaResponse'

  Retailer422Error:
    additionalProperties:
      email_address:
        type: array
        items: string
      name:
        type: array
        items: string
      product_tier:
        type: array
        items: string
      retailer_code:
        type: array
        items: string
      store_profile:
        type: array
        items: string

  Retailer422Response:
    required:
      - data
      - errors
      - meta
    properties:
      data:
        $ref: '#/definitions/emptyObject'
      errors:
        $ref: '#/definitions/Retailer422Error'
      meta:
        $ref: '#/definitions/metaResponse'

  Store422Error:
    additionalProperties:
      centre_id:
        type: array
        items: string
      name:
        type: array
        items: string
      phone_number:
        type: array
        items: string
      retailer_id:
        type: array
        items: string
      salience:
        type: array
        items: string

  Store422Response:
    required:
      - data
      - errors
      - meta
    properties:
      data:
        $ref: '#/definitions/emptyObject'
      errors:
        $ref: '#/definitions/Store422Error'
      meta:
        $ref: '#/definitions/metaResponse'

# Request paths
# -------------
paths:

  /stores:
    post:
      summary: Creates a store
      description: Creates a store in a Westfield Centre and returns it.
      parameters:
        - name: accepts_giftcards
          description: Flag indicating if the store accepts Westfield gift cards
          type: boolean
          in: formData
        - name: category_ids
          description: List of categories the store belongs to
          type: array
          items:
            type: integer
          in: formData
        - name: centre_id
          description: ID of the Westfield centre the store is in
          type: string
          in: formData
        - name: description
          description: Long description of the store's retailer
          type: string
          in: formData
        - name: dining_cuisine
          description: Cuisine offered by the store if it provides dining facilities
          type: string
          in: formData
        - name: dining_image_ref
          description: Storage provider ID of the dining image of the store if it provides dining facilities
          type: string
          in: formData
        - name: dining_menu_ref
          description: Storage provider ID of the menu of the store if it provides dining facilities
          type: string
          in: formData
        - name: dining_price_guide
          description: Number indicating the relative price of dining at the store
          type: integer
          in: formData
        - name: disabled_date
          description: Date the store was disabled in the Westfield system
          type: string
          format: date-time
          in: formData
        - name: email_address
          description: E-mail address of the store
          type: string
          in: formData
        - name: enabled
          description: Flag indicating if the store is enabled in the Westfield system
          type: boolean
          in: formData
        - name: enabled_date
          description: Date the store was enabled in the Westfield system
          type: string
          format: date-time
          in: formData
        - name: featured
          description: Flag indicating if the store is currently being promoted on the website
          type: boolean
          in: formData
        - name: lease_number
          description: Number of the store's lease with Westfield
          type: string
          in: formData
        - name: locations
          description: "List of jibestream locations and meta data"
          in: body
          schema:
            $ref: "#/definitions/locations"
        - name: major
          description: Flag indicating that stores, such as anchor stores, are major in their centre
          type: boolean
          in: formData
        - name: name
          description: Name of the store
          type: string
          in: formData
        - name: phone_number
          description: Phone number of the store
          type: string
          in: formData
        - name: retailer_id
          description: ID of the retailer the store belongs to
          type: integer
          in: formData
        - name: salience
          description: Numeric value used for wayfinding applications
          type: integer
          in: formData
        - name: shop_number
          description: The shop number in the Westfield centre the store occupies
          type: string
          in: formData
        - name: store_front_image_ref
          description: Storage provider ID of the store's store front image
          type: string
          in: formData
        - name: url
          description: URL of the store's website
          type: string
          in: formData
      responses:
        201:
          description: Details of the newly created store
          schema:
            $ref: "#/definitions/storeResponse"
        401:
          description: Unauthorized
          schema:
            $ref: "#/definitions/401Response"
        406:
          description: Not acceptable format
          schema:
            $ref: "#/definitions/406Response"
        422:
          description: Store is invalid
          schema:
            $ref: '#/definitions/Store422Response'