refactor for multiple host path within openapi3 Here specs

Author: AleDore

openapi/here.yaml

@@ -0,0 +1,272 @@
+
+swagger: "2.0"
+info:
+  title: Geocoding and Search API v7
+  version: '7.65'
+  description: This document describes the Geocoding and Search API.
+
+host: autocomplete.search.hereapi.com
+basePath: "/v1"
+parameters:
+  apiKey:
+    description: |
+      API key used to authorize requests.
+        For more information, see https://developer.here.com/documentation/authentication/dev_guide/topics/api-key-credentials.html.
+    name: apiKey
+    type: string
+    required: true
+    in: query
+    minLength: 1
+  qAutocomplete:
+    name: q
+    description: |
+      Enter a free-text query
+
+      Examples:
+        * `ber`, `berl`, `berli`, ...
+        * `berlin+p`, `berlin+paris`, `berlin+parise`, ...
+        * `berlin+pariser+20`
+
+        _Note: Whitespace, urls, email addresses, or other out-of-scope queries will yield no results._
+    in: query
+    required: true
+    type: string
+    minLength: 1
+  inAutocompleteGeocode:
+    name: in
+    description: |+
+      Search within a geographic area. This is a hard filter. Results will be returned if they are located within the specified area.
+
+      A geographic area can be
+
+        * a country (or multiple countries), provided as comma-separated [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country codes
+
+          The country codes are to be provided in all uppercase.
+
+          Format: `countryCode:{countryCode}[,{countryCode}]*`
+
+          Examples:
+          * `countryCode:USA`
+          * `countryCode:CAN,MEX,USA`
+
+    in: query
+    required: false
+    type: string
+    minLength: 1
+
+  limitAutocomplete:
+    name: limit
+    description: Maximum number of results to be returned.
+    in: query
+    required: false
+    type: integer
+    minimum: 1
+    maximum: 20
+    default: 5
+
+  langAutocomplete:
+    name: lang
+    description: |
+      Select the preferred response language for result rendering from a list of BCP47 compliant Language Codes.
+      The autocomplete endpoint tries to detect the query language based on matching name variants and then chooses the same language for the response.
+
+      Therefore the end-user can see and recognize all the entered terms in the same language as in the query.
+      The specified preferred language is used only for not matched address tokens and for matched address tokens in case of ambiguity
+    in: query
+    type: string
+    minLength: 1
+    default: it_IT
+    
+definitions:
+    Address:
+      type: object
+      properties:
+        label:
+          type: string
+          description: 'Assembled address value built out of the address components
+            according to the regional postal rules. These are the same rules for all
+            endpoints. It may not include all the input terms. For example: "Schulstraße
+            4, 32547 Bad Oeynhausen, Germany"'
+        countryCode:
+          type: string
+          description: 'A three-letter country code. For example: "DEU"'
+        countryName:
+          type: string
+          description: 'The localised country name. For example: "Deutschland"'
+        stateCode:
+          type: string
+          description: 'A state code or state name abbreviation – country specific.
+            For example, in the United States it is the two letter state abbreviation:
+            "CA" for California.'
+        state:
+          type: string
+          description: 'The state division of a country. For example: "North Rhine-Westphalia"'
+        countyCode:
+          type: string
+          description: 'A county code or county name abbreviation – country specific.
+            For example, for Italy it is the province abbreviation: "RM" for Rome.'
+        county:
+          type: string
+          description: A division of a state; typically, a secondary-level administrative
+            division of a country or equivalent.
+        city:
+          type: string
+          description: 'The name of the primary locality of the place. For example:
+            "Bad Oyenhausen"'
+        district:
+          type: string
+          description: 'A division of city; typically an administrative unit within
+            a larger city or a customary name of a city''s neighborhood. For example:
+            "Bad Oyenhausen"'
+        subdistrict:
+          type: string
+          description: 'A subdivision of a district. For example: "Minden-Lübbecke"'
+        street:
+          type: string
+          description: 'Name of street. For example: "Schulstrasse"'
+        block:
+          type: string
+          description: Name of block.
+        subblock:
+          type: string
+          description: Name of sub-block.
+        postalCode:
+          type: string
+          description: 'An alphanumeric string included in a postal address to facilitate
+            mail sorting, such as post code, postcode, or ZIP code. For example: "32547"'
+        houseNumber:
+          type: string
+          description: 'House number. For example: "4"'
+    ErrorResponse:
+      type: object
+      required:
+      - status
+      - title
+      - correlationId
+      - requestId
+      properties:
+        status:
+          type: integer
+          format: int32
+          description: The HTTP status code
+        title:
+          type: string
+          description: Human-readable error description
+        code:
+          type: string
+          description: Error code
+        cause:
+          type: string
+          description: Human-readable explanation for the error
+        action:
+          type: string
+          description: Human-readable action for the user
+        correlationId:
+          type: string
+          description: Auto-generated ID univocally identifying this request
+        requestId:
+          type: string
+          description: Request identifier provided by the user
+
+    OpenSearchAutocompleteResponse:
+      type: object
+      required:
+      - items
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/definitions/AutocompleteResultItem"
+          description: The results are presented as a JSON list of candidates in ranked
+            order (most-likely to least-likely) based on the matched location criteria.
+    AutocompleteResultItem:
+      type: object
+      required:
+      - title
+      - address
+      properties:
+        title:
+          type: string
+          description: 'The unified display name of this result item. The result title
+            is composed so that the customer application can use it to render the
+            suggestions with highlighting. It is build in a unified way for all the
+            countries starting from the country name and down to the address line.
+            It is build out of the address components that are important for the end-user
+            to recognize and eventually to choose a result and includes all the input
+            terms. For example: "Germany, 32547, Bad Oeynhausen, Schulstraße 4"'
+        id:
+          type: string
+          description: The unique identifier for the result item. This ID can be used
+            for a Look Up by ID search as well.
+        resultType:
+          type: string
+          enum:
+          - administrativeArea
+          - locality
+          - street
+          - intersection
+          - addressBlock
+          - houseNumber
+          - postalCodePoint
+          - place
+          description: 'WARNING: The resultType values ''intersection'' and ''postalCodePoint''
+            are in BETA state'
+        houseNumberType:
+          type: string
+          enum:
+          - PA
+          - interpolated
+        localityType:
+          type: string
+          enum:
+          - postalCode
+          - subdistrict
+          - district
+          - city
+        administrativeAreaType:
+          type: string
+          enum:
+          - county
+          - state
+          - country
+        address:
+          $ref: "#/definitions/Address"
+          description: Detailed address of the result item.
+        distance:
+          type: integer
+          format: int64
+          description: 'The distance from the search center to this result item in
+            meters. For example: "172039"'
+paths:  
+  "/autocomplete":
+    get:
+      operationId: autocomplete
+      summary: Autocomplete
+      description: 'BETA: This endpoint completes the few entered keystrokes to the
+        valid street address or administrative area to speed-up entering the address
+        queries.'
+      parameters:
+        - $ref: "#/parameters/apiKey"
+        - $ref: "#/parameters/qAutocomplete"
+        - $ref: "#/parameters/inAutocompleteGeocode"
+        - $ref: "#/parameters/limitAutocomplete"
+        - $ref: "#/parameters/langAutocomplete"
+      responses:
+        '200':
+          description: The search results.
+          schema:
+            $ref: "#/definitions/OpenSearchAutocompleteResponse"
+        '400':
+          description: 'Client error: request failed validation.'
+          schema:
+            $ref: "#/definitions/ErrorResponse"
+        '405':
+          description: 'Client error: http method not supported.'
+          schema:
+            $ref: "#/definitions/ErrorResponse"
+        '503':
+          description: Temporary server error.
+          schema:
+            $ref: "#/definitions/ErrorResponse"
+  
+