feat(specs): add specific documentation for facets query parameter in Composition API (#5477)

Author: ClaraMuller

specs/composition/common/params/Composition.yml

@@ -1,3 +1,23 @@
+# #########################
+# ### Category Faceting ###
+# #########################
+
+facets:
+  type: array
+  items:
+    type: string
+  description: |
+    Facets for which to retrieve facet values that match the search criteria and the number of matching facet values
+    To retrieve all facets, use the wildcard character `*`.
+    To retrieve disjunctive facets lists, annotate any facets with the `disjunctive` modifier.
+    For more information, see [facets](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#contextual-facet-values-and-counts) and [disjunctive faceting for Smart Groups](https://www.algolia.com/doc/guides/managing-results/compositions/search-based-groups#facets-including-disjunctive-faceting).
+  default: []
+  example:
+    - ['category', 'disjunctive(brand)', 'price']
+    - ['*']
+  x-categories:
+    - Faceting
+
 # ######################
 # ### Category Rules ###
 # ######################

specs/composition/common/params/Search.yml

@@ -70,9 +70,6 @@ enableRules:
 exactOnSingleWordQuery:
   $ref: '../../../common/schemas/IndexSettings.yml#/exactOnSingleWordQuery'
 
-facets:
-  $ref: '../../../common/schemas/SearchParams.yml#/baseSearchParamsWithoutQuery/properties/facets'
-
 facetFilters:
   $ref: '../../../common/schemas/SearchParams.yml#/facetFilters'
 

specs/composition/common/schemas/components/Injection.yml

@@ -110,7 +110,7 @@ mainInjectionQueryParameters:
         facetingAfterDistinct:
           $ref: '../../params/Search.yml#/facetingAfterDistinct'
         facets:
-          $ref: '../../params/Search.yml#/facets'
+          $ref: '../../params/Composition.yml#/facets'
         hitsPerPage:
           $ref: '../../params/Search.yml#/hitsPerPage'
         maxValuesPerFacet:

specs/composition/common/schemas/requestBodies/RunParams.yml

@@ -13,10 +13,10 @@ params:
       $ref: '../../params/Composition.yml#/getRankingInfo'
     relevancyStrictness:
       $ref: '../../params/Search.yml#/relevancyStrictness'
-    facets:
-      $ref: '../../params/Search.yml#/facets'
     facetFilters:
       $ref: '../../params/Search.yml#/facetFilters'
+    facets:
+      $ref: '../../params/Composition.yml#/facets'
     optionalFilters:
       $ref: '../../params/Search.yml#/optionalFilters'
     numericFilters: