CHA-915: add the POST products-uuid/search doc (#945)

Co-authored-by: hogren <[email protected]>

Author: guillaumefer-akeneo

Diff for: content/swagger/akeneo-web-api.json

@@ -1,5 +1,7 @@
 /api/rest/v1/products-uuid:
   $ref: ./resources/products_uuid/routes/products_uuid.yaml
+/api/rest/v1/products-uuid/search:
+    $ref: ./resources/products_uuid/routes/products_uuid_search.yaml
 /api/rest/v1/products-uuid/{uuid}:
   $ref: ./resources/products_uuid/routes/products_uuid_uuid.yaml
 /api/rest/v1/products-uuid/{uuid}/proposal:

Diff for: content/swagger/paths.yaml

@@ -0,0 +1,84 @@
+post:
+  summary: Search list of products
+  operationId: "search_products_uuid"
+  tags:
+    - Product [uuid]
+  x-versions:
+    - "SaaS"
+  description: |
+    This endpoint allows you to search for products that match the filters provided in the request body. Products are paginated and can be filtered by scope, locales, attributes, and other criteria. User-group-based permissions are applied to the products you request.
+    <br /><br />
+    <b>Important limitations</b><br />
+    - The maximum number of attributes in the request body is 800.<br />
+    - The maximum number of search criteria is 20.<br />
+    - The maximum number of items in an array (e.g., values for filters like <code>IN</code> or <code>NOT IN</code>) is 800.
+
+  parameters:
+    - $ref: '#/parameters/pagination_type'
+    - $ref: '#/parameters/page'
+    - $ref: '#/parameters/search_after'
+    - $ref: '#/parameters/limit'
+    - $ref: '#/parameters/with_count'
+    - name: body
+      in: body
+      required: true
+      schema:
+        type: object
+        properties:
+          search:
+            type: string
+            description: Filter products, for more details see the <a href="/documentation/filter.html">Filters</a> section
+          scope:
+            type: string
+            description: Filter product values to return scopable attributes for the given channel as well as the non-localizable/non-scopable attributes. For more details, see  the <a href="/documentation/filter.html#via-channel">Filter product values via channel</a> section
+          locales:
+            type: string
+            description: Filter product values to return localizable attributes for the given locales as well as the non-localizable/non-scopable attributes. For more details, see the <a href="/documentation/filter.html#via-locale">Filter product values via locale</a> section
+          attributes:
+            type: string
+            description: Filter product values to only return those concerning the given attributes. For more details, see the <a href="/documentation/filter.html#filter-product-values">Filter on product values</a> section
+          with_attribute_options:
+            type: boolean
+            description: Return labels of attribute options in the response. See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details. (Only available since the 5.0 version)
+          with_asset_share_links:
+            type: boolean
+            description: Return asset collection share link urls in the response. See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details. (Only available in the SaaS version)
+          with_quality_scores__products:
+            type: boolean
+            description: Return product quality scores in the response. (Only available since the 5.0 version)
+          with_completenesses:
+            type: boolean
+            description: Return product completenesses in the response. (Only available since the 6.0 version)
+        x-examples:
+          x-example-1:
+            '{"scope": "ecommerce","locales": ["en_US"],"search": {"completeness":[{"operator": "=","value": 100,"scope": "ecommerce"}]}}'
+          x-example-2:
+            '{"attributes": ["sku","colors","a_localized_and_scopable_text_area"],"scope": "tablet"}'
+  responses:
+    200:
+      description: Return products paginated
+      schema:
+        title: Products
+        type: object
+        allOf:
+          - $ref: '#/definitions/Pagination'
+          - properties:
+              _embedded:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/definitions/ProductUuidList'
+      x-examples-per-version:
+        - x-version: 'SaaS'
+          x-example:
+            $ref: '#/definitions/ProductUuidExamples/x-SaaS'
+    401:
+      $ref: "#/responses/401Error"
+    403:
+      $ref: "#/responses/403Error"
+    406:
+      $ref: "#/responses/406Error"
+    422:
+      $ref: "#/responses/422Error"