demo swagger 2

swagger: '2.0'
info:
  title: HostelsClub API
  description: HostelsClub API
  version: "1.0.0"
# the domain of the service
host: api.hostelsclub.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json

# ----------------------------------------------------------------------------
# ENDPOINTS
# ----------------------------------------------------------------------------

paths:
  # STATIC HELPERS
  # ----------------------------------------------------------------------------
  /cities:
    get:
      summary: Cities
      description: |
        Returns a list of the cities known in the system that match the query 
        entered. This data will be used in the search API to restrict the search 
        for properties in a specific city.
      parameters:
        - name: country_id
          in: query
          description: Country ID.
          required: true
          type: string
      tags:
        - StaticHelpers
      responses:
        200:
          description: An array of cities.
          schema:
            type: array
            items:
              $ref: '#/definitions/Mapping'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  
 
# ----------------------------------------------------------------------------
# DEFINITIONS
# ----------------------------------------------------------------------------
definitions:

  
  City:
    type: object
    properties:
      id:
        type: string
        description: Unique identifier representing a specific city.
      city_name:
        type: string
        description: Name of city.
  Mapping:
    type: object
    properties:
      id:
        type: number
      object: 
        $ref: '#/definitions/City'
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string