docs: Improve api def ingredient schema (#10886)

This pull request updates the `ingredients.yaml` and
`product_ingredients.yaml` file to improve the schema definitions and
ensure conformity with OpenAPI 3.1 specification. Specifically, it
includes:

- Support better the self reference (SDK client gen compliant)
correcting the `$ref` path for `ingredients`.
- Added descriptions for properties.
- Ensured all types are correct and conform to OpenAPI 3.1
specification.

docs/api/ref/api.yml

@@ -516,15 +516,15 @@ components:
       required: true
     page:
       schema:
-        type: int
+        type: integer
         example: 24
       in: query
       name: page
       description: |
         The page number you request to view (eg. in search results spanning multiple pages)
     page_size:
       schema:
-        type: int
+        type: integer
         example: 24
       in: query
       name: page_size

docs/api/ref/requestBodies/add_or_edit_a_product.yaml

@@ -16,33 +16,24 @@ properties:
     example: mypassword
   comment:
     type: string
-    description: A comment for the change. It will be shown in product changes history.
+    description: A comment for the change. It will be shown in product changes history.
     example: new packaging from super-app
   brands:
-    schema:
-      type: array
-      items:
-        type: string
-    style: form
-    explode: false
+    type: array
+    items:
+      type: string
     description: The brands of the product (comma separated list of values).
     example: Häagen-Dazs,General-mills
   labels:
-    schema:
-      type: array
-      items:
-        type: string
-    style: form
-    explode: false
+    type: array
+    items:
+      type: string
     description: The labels of the product (comma separated list of values).
     example: Kosher,Ferroro
   categories:
-    schema:
-      type: array
-      items:
-        type: string
-    style: form
-    explode: false
+    type: array
+    items:
+      type: string
     description: The categories of the product (comma separated list of values).
     example: Desserts,Frozen foods
   packaging:

docs/api/ref/responses/get_nutrients.yaml

@@ -1 +1 @@
-$ref: ../schemas/nutrients.yaml
+$ref: '../schemas/nutrients.yaml#/components/schemas/Nutrients'

docs/api/ref/responses/get_product_by_barcode.yaml

@@ -3,9 +3,6 @@ x-stoplight:
 type: object
 allOf:
   - $ref: ./get_product_by_barcode_base.yaml
-  - type: object
-    properties:
+  - properties:
       product:
-        type: object
-        allOf:
-          - $ref: ../schemas/product.yaml
+        $ref: ../schemas/product.yaml

docs/api/ref/schemas/ingredient.yaml

@@ -1,30 +1,43 @@
-type: array
-description: |
-  This structure gives the different ingredients and some information about them,
-  like estimate on their quantity.
-items:
-  type: object
-  properties:
-    id:
-      type: string
-    ingredients:
+components:
+  schemas:
+    Ingredients:
+      type: array
       description: |
-        Sub ingredients composing this ingredients.
-      # self recursive
-      $ref: "#"
-    percent:
-      type: integer
-    percent_estimate:
-      type:
-        - number
-    percent_max:
-      type:
-        - number
-    percent_min:
-      type: integer
-    text:
-      type: string
-    vegan:
-      type: string
-    vegetarian:
-      type: string
+        This structure gives the different ingredients and some information about them,
+        like estimate on their quantity.
+      items:
+        type: object
+        title: ingredient
+        properties:
+          id:
+            type: string
+          ingredients:
+            description: |
+              Sub ingredients composing this ingredients.
+            # self recursive
+            type: array
+            items:
+              $ref: '#/components/schemas/Ingredients/items'
+          percent:
+            type: integer
+            description: The percentage of the ingredient.
+          percent_estimate:
+            type: number
+            description: Estimated percentage of the ingredient.
+          percent_max:
+            type: 
+              - 'string'
+              - 'number'
+            description: Maximum percentage of the ingredient.
+          percent_min:
+            type: integer
+            description: Minimum percentage of the ingredient.
+          text:
+            type: string
+            description: Text description of the ingredient.
+          vegan:
+            type: string
+            description: Indicates if the ingredient is vegan.
+          vegetarian:
+            type: string
+            description: Indicates if the ingredient is vegetarian.

docs/api/ref/schemas/knowledge_panels/elements/element.yaml

@@ -6,7 +6,7 @@ description: |
   Each element object contains one specific element object such as a text element or an image element.
 properties:
   type:
-    element_type: string
+    type: string
     enum:
       - text
       - image

docs/api/ref/schemas/nutrients.yaml

@@ -1,26 +1,32 @@
-type: array
-description: |
-  Nutrients and sub-nutrients of a product, with their name and default unit.
-items:
-  type: object
-  properties:
-    id:
-      type: string
-      description: id of the nutrient
-    name:
-      type: string
-      description: Name of the nutrient in the requested language
-    important:
-      type: boolean
-      description: Indicates if the nutrient is always shown on the nutrition facts table
-    display_in_edit_form:
-      type: boolean
-      description: Indicates if the nutrient should be shown in the nutrition facts edit form
-    unit:
-      description: Default unit of the nutrient
-      $ref: "./nutrient_unit.yaml"
-    nutrients:
+components:
+  schemas:
+    type: object
+    Nutrients:
+      type: array
       description: |
-        Sub-nutrients (e.g. saturated-fat is a sub-nutrient of fat).
-      # self recursive
-      $ref: "#/"
+        Nutrients and sub-nutrients of a product, with their name and default unit.
+        (e.g. saturated-fat is a sub-nutrient of fat).
+      items:
+        type: object
+        title: nutrient
+        properties:
+          id:
+            type: string
+            description: id of the nutrient
+          name:
+            type: string
+            description: Name of the nutrient in the requested language
+          important:
+            type: boolean
+            description: Indicates if the nutrient is always shown on the nutrition facts table
+          display_in_edit_form:
+            type: boolean
+            description: Indicates if the nutrient should be shown in the nutrition facts edit form
+          unit:
+            description: Default unit of the nutrient
+            $ref: "./nutrient_unit.yaml"
+          nutrients:
+            type: array
+            items:
+              # self recursive
+              $ref: "#/components/schemas/Nutrients/items"

docs/api/ref/schemas/product_ingredients.yaml

@@ -1,4 +1,5 @@
 type: object
+title: product_ingredients
 description: Fields about ingredients of a product
 properties:
 
@@ -22,7 +23,7 @@ properties:
       type: string
 
   ingredients:
-    $ref: ./ingredient.yaml
+    $ref: './ingredient.yaml#/components/schemas/Ingredients'
   ingredients_analysis:
     type: object
     properties: