docs: update details on retrieving nested categories (#10317)

www/utils/generated/oas-output/operations/admin/get_admin_product-categories.ts

@@ -111,20 +111,20 @@
  *             description: A parent category's ID.
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to include the parent category of each category. If enabled, the parent category is set in the `parent_category` property of each category object.
+ *     description: Whether to include the parent category of each category. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to include the parent category of each category. If enabled, the parent category is set in the `parent_category` property of each category object.
+ *       description: Whether to include the parent category of each category. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to include the child categories of each category. If enabled, the child categories are added to the `category_children` property of each category object.
+ *     description: Whether to include the child categories of each category. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to include the child categories of each category. If enabled, the child categories are added to the `category_children` property of each category object.
+ *       description: Whether to include the child categories of each category. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *   - name: is_internal
  *     in: query
  *     description: Filter by whether the category is internal.

www/utils/generated/oas-output/operations/admin/get_admin_product-categories_[id].ts

@@ -25,20 +25,20 @@
  *         url: "#select-fields-and-relations"
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *     description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *       description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *     description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *       description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  * security:
  *   - api_token: []
  *   - cookie_auth: []

www/utils/generated/oas-output/operations/store/get_store_product-categories.ts

@@ -114,20 +114,20 @@
  *             description: A product category's ID.
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *     description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *       description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *     description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the child of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *       description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the child of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *   - name: created_at
  *     in: query
  *     description: Filter by the category's creation date.

www/utils/generated/oas-output/operations/store/get_store_product-categories_[id].ts

@@ -28,20 +28,20 @@
  *         url: "#select-fields-and-relations"
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *     description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *       description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *     description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *       description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL