fix(specs): query suggestions api (#2924)

Co-authored-by: shortcuts <vannicattec@gmail.com>

specs/query-suggestions/common/enums.yml

@@ -2,7 +2,7 @@ LogLevel:
   title: level
   type: string
   description: |
-    The type of log entry. 
+    Type of log entry.
 
     - `SKIP`. A query is skipped because it doesn't match the conditions for successful inclusion. For example, when a query doesn't generate enough search results.
     - `INFO`. An informative log entry.

specs/query-suggestions/common/responses/BadRequest.yml

@@ -2,31 +2,33 @@ description: Bad Request.
 content:
   application/json:
     schema:
-      $ref: '../schemas/BaseResponse.yml'
+      $ref: './BaseResponse.yml'
     examples:
       IndexNameRequired:
         summary: Index name required.
-        value: {'status': 400, 'message': 'IndexName cannot be empty'}
+        value:
+          status: 400
+          message: IndexName cannot be empty.
       SourceIndicesRequired:
         summary: Source indices required.
         value:
-          'status': 400
-          'message': 'Invalid body "sourceIndices needs to contain at least one index".'
-          
+          status: 400
+          message: Invalid body "sourceIndices needs to contain at least one index".
+
       SourceIndexNameRequired:
         summary: Source index name required.
         value:
-          'status': 400
-          'message': 'Invalid body "every source index must have an `indexName`".'
-          
+          status: 400
+          message: Invalid body "every source index must have an `indexName`".
+
       MinHitsPositive:
         summary: MinHits must be positive.
         value:
-          'status': 400
-          'message': 'Invalid body "every source index `minHits` must be positive".'
-          
+          status: 400
+          message: Invalid body "every source index `minHits` must be positive".
+
       MinLettersPositive:
         summary: MinLetters must be positive.
         value:
-          'status': 400
-          'message': 'Invalid body "every source index `minLetters` must be positive".'
+          status: 400
+          message: Invalid body "every source index `minLetters` must be positive".

specs/query-suggestions/common/schemas/BaseResponse.yml → specs/query-suggestions/common/responses/BaseResponse.yml

@@ -1,5 +1,4 @@
 type: object
-additionalProperties: false
 properties:
   status:
     type: integer

specs/query-suggestions/common/responses/InternalError.yml

@@ -2,8 +2,10 @@ description: Internal Server Error.
 content:
   application/json:
     schema:
-      $ref: '../schemas/BaseResponse.yml'
+      $ref: './BaseResponse.yml'
     examples:
       Error:
         description: This error can happen if you use a non-existing `indexName` as a path parameter when trying to update or delete a Query Suggestions configuration.
-        value: {'status': 500, 'message': 'Internal Server Error'}
+        value:
+          status: 500
+          message: Internal Server Error

specs/query-suggestions/common/responses/NotFound.yml

@@ -2,8 +2,10 @@ description: Not Found.
 content:
   application/json:
     schema:
-      $ref: '../schemas/BaseResponse.yml'
+      $ref: './BaseResponse.yml'
     examples:
       NotFound:
         summary: Index not found.
-        value: {'status': 404, 'message': 'Not Found'}
+        value:
+          status: 404
+          message: Not Found

specs/query-suggestions/common/responses/QuerySuggestionsConfigurationResponse.yml

@@ -0,0 +1,20 @@
+QuerySuggestionsConfigurationResponse:
+  type: object
+  description: API response for retrieving Query Suggestions configurations.
+  allOf:
+    - $ref: '#/AppID'
+    - $ref: '../schemas/QuerySuggestionsConfiguration.yml#/QuerySuggestionsConfigurationWithIndex'
+  required:
+    - appID
+    - allowSpecialCharacters
+    - enablePersonalization
+    - exclude
+    - languages
+    - sourceIndices
+
+AppID:
+  type: object
+  properties:
+    appID:
+      type: string
+      description: Algolia application ID to which this Query Suggestions configuration belongs.

specs/query-suggestions/common/responses/Unauthorized.yml

@@ -2,24 +2,27 @@ description: Unauthorized
 content:
   application/json:
     schema:
-      $ref: '../schemas/BaseResponse.yml'
+      $ref: './BaseResponse.yml'
     examples:
       Unauthorized:
         summary: Wrong region.
         description: |
-          Make sure to make your request to the server corresponding to your region.  
+          Make sure to make your request to the server corresponding to your region.
 
           You can check the region for your application in the [Algolia dashboard](https://dashboard.algolia.com/account/infrastructure/analytics).
         value:
-          'status': 401
-          'message': 'The log processing region does not match'
-          
+          status: 401
+          message: The log processing region does not match.
+
       InvalidCredentials:
         summary: Invalid credentials.
         description: Your application ID or API key is wrong.
-        value: {'status': 401, 'message': 'Invalid credentials'}
+        value:
+          status: 401
+          message: Invalid credentials
       MissingACL:
         summary: Key is missing ACL.
         description: Your API key is missing the required ACL for this operation.
         value:
-          {'status': 401, 'message': 'The provided API key is missing the \"editSettings\" ACL'}
+          status: 401
+          message: The provided API key is missing the \"editSettings\" ACL.

specs/query-suggestions/common/responses/UnprocessableEntity.yml

@@ -2,10 +2,10 @@ description: Unprocessable Entity.
 content:
   application/json:
     schema:
-      $ref: '../schemas/BaseResponse.yml'
+      $ref: './BaseResponse.yml'
     examples:
       UnprocessableEntity:
         summary: Configuration already exists.
-        value: 
-          'status': 422
-          'message': 'Configuration already exists for index: test-qs'
+        value:
+          status: 422
+          message: 'Configuration already exists for index: test-qs'

specs/query-suggestions/common/schemas/QuerySuggestionsConfiguration.yml

@@ -1,25 +1,184 @@
-type: object
-description: Query Suggestions configuration.
-additionalProperties: false
-required:
-  - sourceIndices
-properties:
-  sourceIndices:
-    $ref: './SourceIndices.yml'
-  languages:
-    $ref: './Languages.yml'
-  exclude:
-    oneOf:
-      - type: array
-        description: Patterns to exclude from query suggestions.
+QuerySuggestionsConfigurationWithIndex:
+  type: object
+  description: Query Suggestions configuration.
+  required:
+    - indexName
+    - sourceIndices
+  allOf:
+    - type: object
+      properties:
+        indexName:
+          $ref: './QuerySuggestionsIndexName.yml'
+    - $ref: '#/QuerySuggestionsConfiguration'
+
+QuerySuggestionsConfiguration:
+  type: object
+  description: Query Suggestions configuration.
+  required:
+    - sourceIndices
+  properties:
+    sourceIndices:
+      type: array
+      description: Algolia indices from which to get the popular searches for query suggestions.
+      minItems: 1
+      items:
+        $ref: '#/SourceIndex'
+    languages:
+      $ref: '#/Languages'
+    exclude:
+      $ref: '#/Exclude'
+    enablePersonalization:
+      type: boolean
+      default: false
+      description: Whether to turn on personalized query suggestions.
+    allowSpecialCharacters:
+      type: boolean
+      default: false
+      description: Whether to include suggestions with special characters.
+
+Exclude:
+  title: exclude
+  description: Words or regular expressions to exclude from the suggestions.
+  default: null
+  oneOf:
+    - type: array
+      items:
+        type: string
+    - type: 'null'
+
+Languages:
+  title: languages
+  description: |
+    Languages for deduplicating singular and plural suggestions.
+    If specified, only the more popular form is included.
+  default: false
+  oneOf:
+    - type: array
+      description: Languages for which to deduplicate singular and plural forms.
+      items:
+        type: string
+        description: Two-letter country code.
+    - type: boolean
+      description: If true, deduplication is enabled for all languages.
+
+SourceIndex:
+  type: object
+  description: Configuration of an Algolia index for Query Suggestions.
+  required:
+    - indexName
+  properties:
+    indexName:
+      type: string
+      description: Name of the Algolia index to use as source for query suggestions.
+      example: products
+    replicas:
+      type: boolean
+      default: false
+      description: |
+        If true, Query Suggestions uses all replica indices to find popular searches.
+        If false, only the primary index is used.
+      example: false
+    analyticsTags:
+      $ref: '#/AnalyticsTags'
+    facets:
+      $ref: '#/Facets'
+    minHits:
+      type: integer
+      minimum: 0
+      default: 5
+      description: |
+        Minimum number of hits required to be included as a suggestion.
+
+        A search query must at least generate `minHits` search results to be included in the Query Suggestions index.
+    minLetters:
+      type: integer
+      minimum: 0
+      default: 4
+      description: |
+        Minimum letters required to be included as a suggestion.
+
+        A search query must be at least `minLetters` long to be included in the Query Suggestions index.
+    generate:
+      $ref: '#/Generate'
+    external:
+      $ref: '#/External'
+
+AnalyticsTags:
+  title: analyticsTags
+  description: |
+    Analytics tags for filtering the popular searches.
+    For more information, see [Segment your analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments/).
+  default: null
+  oneOf:
+    - type: array
+      items:
+        type: string
+    - type: 'null'
+
+Facets:
+  title: facets
+  description: |
+    Facets to use as top categories with your suggestions.
+
+    If provided, Query Suggestions adds the top facet values to each suggestion.
+  default: null
+  oneOf:
+    - type: array
+      items:
+        $ref: '#/Facet'
+    - type: 'null'
+  example:
+    - attribute: category
+      amount: 3
+    - attribute: brand
+      amount: 2
+
+Facet:
+  type: object
+  description: Facet to use as category.
+  properties:
+    attribute:
+      type: string
+      description: Facet name.
+    amount:
+      type: integer
+      description: Number of suggestions.
+
+Generate:
+  title: generate
+  description: |
+    Facets used for generating query suggestions from facet values.
+
+    For example, if you set `generate: ["color", "brand"]`, combinations from the facet values are added as query suggestions,
+    such as "blue adidas", "red adidas", "blue nike", "red nike", etc.
+
+    You can include nested lists.
+  default: null
+  oneOf:
+    - type: array
+      items:
+        type: array
         items:
           type: string
-      - type: 'null'
-  enablePersonalization:
-    type: boolean
-    default: false
-    description: Turn on personalized query suggestions.
-  allowSpecialCharacters:
-    type: boolean
-    default: false
-    description: Allow suggestions with special characters.
+    - type: 'null'
+  example:
+    - [color, brand]
+
+External:
+  description: |
+    Algolia indices with popular searches to use as query suggestions.
+
+    Records of these indices must have these attributes:
+
+    - `query`: search query which will be added as a suggestion
+    - `count`: measure of popularity of that search query
+
+    For example, you can export popular searches from an external analytics provider, such as Google Analytics or Adobe Analytics,
+    and feed this data into an Algolia index.
+    You can use this index to generate query suggestions until your Algolia Analytics has collected enough data.
+  default: null
+  oneOf:
+    - type: array
+      items:
+        type: string
+    - type: 'null'