docs: Improved descriptions and schema adjustments for API references

docs/api/ref/api.yml

@@ -531,8 +531,11 @@ components:
     Product:
       $ref: ./schemas/product.yaml
     Ingredient:
-      # Added to fix some generator errors on $ref
+      # Added to fix some generator errors on recursive $ref
       $ref: "./schemas/ingredient.yaml#/components/schemas/Ingredient"
+    Nutrient:
+      # Added to fix some generator errors on recursive $ref
+      $ref: "./schemas/nutrients.yaml#/components/schemas/Nutrient"
   parameters:
     id:
       schema:

docs/api/ref/schemas/image.yaml

@@ -1,34 +1,40 @@
-type: object
-title: image
-description: |
-  This object represent an image that was uploaded to a product.
-  "imgid" is an integer which is a sequential number unique to each picture.
-properties:
-  sizes:
-    type: object
-    description: |
-      The available image sizes for the product (both reduced and full). 
-      The reduced images are the ones with numbers as the key( 100, 200 etc) 
-      while the full images have `full` as the key.
-    properties:
-      full:
-        $ref: ./image_size.yaml
-    patternProperties:
-      "(?<image_size>100|400)":
-        description: |
-          properties of thumbnail of size `image_size`.
-          **TODO** explain how to compute name
+components:
+  schemas:
+    Sizes:
+      type: object
+      description: |
+        The available image sizes for the product (both reduced and full). 
+        The reduced images are the ones with numbers as the key( 100, 200 etc) 
+        while the full images have `full` as the key.
+      properties:
+        full:
+          $ref: ./image_size.yaml
+      patternProperties:
+        "(?<image_size>100|400)":
+          description: |
+            properties of thumbnail of size `image_size`.
+            **TODO** explain how to compute name
 
-          For real type: see description of property `full`.
-          (Put this way because of a [bug in rapidoc](https://github.com/rapi-doc/RapiDoc/issues/880))
-        type: string
-  uploaded_t:
-    type: string
-    example: "1457680652"
-    description: |
-      The time the image was uploaded (as unix timestamp).
-  uploader:
-    type: string
-    example: openfoodfacts-contributors
-    description: |
-      The contributor that uploaded the image.
+            For real type: see description of property `full`.
+            (Put this way because of a [bug in rapidoc](https://github.com/rapi-doc/RapiDoc/issues/880))
+          type: string
+
+    Image:
+      type: object
+      title: image
+      description: |
+        This object represent an image that was uploaded to a product.
+        "imgid" is an integer which is a sequential number unique to each picture.
+      properties:
+        sizes:
+          $ref: "#/components/schemas/Sizes"
+        uploaded_t:
+          type: string
+          example: "1457680652"
+          description: |
+            The time the image was uploaded (as unix timestamp).
+        uploader:
+          type: string
+          example: openfoodfacts-contributors
+          description: |
+            The contributor that uploaded the image.

docs/api/ref/schemas/image_role.yaml

@@ -1,7 +1,5 @@
 components:
   schemas:
-    ImageSize:
-      $ref: ./image_size.yaml
     ImageRole:
       title: image_role
       type: object
@@ -29,7 +27,10 @@ components:
           #  - type: "boolean"
           #  - type: "string"
           #    enum: ["true", "false"]
-          type: "null"
+          type:
+            - "string"
+            - "boolean"
+            - "null"
           examples:
             - null
             - "false"
@@ -46,21 +47,24 @@ components:
             while the full images have `full` as the key.
           properties:
             "100":
-              $ref: "#/components/schemas/ImageSize"
+              $ref: ./image_size.yaml
             "200":
-              $ref: "#/components/schemas/ImageSize"
+              $ref: ./image_size.yaml
             "400":
-              $ref: "#/components/schemas/ImageSize"
+              $ref: ./image_size.yaml
             full:
-              $ref: "#/components/schemas/ImageSize"
+              $ref: ./image_size.yaml
         white_magic:
           #TODO: should be replaced by something like this once full supported by generator
           #oneOf:
           #  - type: "null"
           #  - type: "boolean"
           #  - type: "string"
           #    enum: ["true", "false"]
-          type: "null"
+          type:
+            - "string"
+            - "boolean"
+            - "null"
           examples:
             - null
             - "false"

docs/api/ref/schemas/image_urls.yaml

@@ -1,5 +1,24 @@
-type: object
-patternProperties:
-  '(?<language_code>\w\w)':
-    type: string
-    description: url of the image for language `language_code`
+components:
+  schemas:
+    ImageUrls:
+      type: object
+      patternProperties:
+        '(?<language_code>\w\w)':
+          type: string
+          description: url of the image for language `language_code`
+    SelectedImage:
+      type: object
+      description: URLs of thumbnails image of image of type `image_type`
+      properties:
+        display:
+          description: |
+            Thumbnail urls of product image (front) adapted to display on product page
+          $ref: "#/components/schemas/ImageUrls"
+        small:
+          description: |
+            Thumbnail urls of product image (front) adapted to display on product list page
+          $ref: "#/components/schemas/ImageUrls"
+        thumb:
+          description: |
+            Thumbnail urls of product image (front) in smallest format
+          $ref: "#/components/schemas/ImageUrls"

docs/api/ref/schemas/nutrients.yaml

@@ -1,31 +1,30 @@
 components:
   schemas:
-    type: object
+    Nutrient:
+      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:
+          $ref: "#/components/schemas/Nutrients"
     Nutrients:
       type: array
       description: |
         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:
-            $ref: "./nutrient_unit.yaml"
-          nutrients:
-            type: array
-            items:
-              # self recursive
-              $ref: "#/components/schemas/Nutrients/items"
+        $ref: "#/components/schemas/Nutrient"

docs/api/ref/schemas/product_base.yaml

@@ -20,8 +20,7 @@ properties:
         and
         A series of mask for the barcode
         It helps retrieve barcodes starting by
-      example: |
-        ["code-13","3017620422xxx","301762042xxxx","30176204xxxxx","3017620xxxxxx","301762xxxxxxx","30176xxxxxxxx","3017xxxxxxxxx","301xxxxxxxxxx","30xxxxxxxxxxx","3xxxxxxxxxxxx"]
+      examples: ["code-13","3017620422xxx","301762042xxxx","30176204xxxxx","3017620xxxxxx","301762xxxxxxx","30176xxxxxxxx","3017xxxxxxxxx","301xxxxxxxxxx","30xxxxxxxxxxx","3xxxxxxxxxxxx"]
   generic_name:
     type: string
     description: |

docs/api/ref/schemas/product_ecoscore.yaml

@@ -14,6 +14,7 @@ properties:
       and complementary data of interest.
     properties:
       adjustments:
+        title: product_ecoscore_adjustments
         type: object
         properties:
           origins_of_ingredients:

docs/api/ref/schemas/product_extended.yaml

@@ -101,25 +101,19 @@ properties:
     type: object
     description: |
       Detail of ingredients or processing that makes the products having Nova 3 or 4
-    properties:
-      "3":
-        description: |
-          Markers of level 3
-        type: array
-        items:
-          type: array
-          description: |
-            This array has two element for each marker.
-            One
-          items:
-            type: string
-      "4":
-        description: |
-          Markers of level 4
+    propertyNames:
+      description: Markers of level 3, 4, ...
+      type: integer
+      enum: [3, 4]
+    additionalProperties:
+      type: array
+      items:
         type: array
+        # minItems: 2
+        # maxItems: 2
         items:
-          # same as above
-          $ref: "#/properties/nova_groups_markers/properties/3/items"
+          description: This array has two elements for each marker. The first element is the tag type of the marker (e.g. "ingredients", "additives", "categories"), and the second is the tag id in the taxonomy (e.g. "en:e471")
+          type: string
 
   nucleotides_tags:
     type: array

docs/api/ref/schemas/product_images.yaml

@@ -17,10 +17,14 @@ properties:
     type: object
     title: product_images_properties
     properties:
-      1:
-        $ref: ./image.yaml
       front:
         $ref: "./image_role.yaml#/components/schemas/ImageRole"
+
+    additionalProperties:
+      $ref: "./image.yaml#/components/schemas/Image"
+    propertyNames:
+      type: integer
+
     patternProperties:
       '(?<imgid>\d+)':
         description: |
@@ -50,24 +54,8 @@ properties:
       This is very handy if you display the product to users.
     properties:
       front:
-        type: object
-        description: URLs of thumbnails image of image of type `image_type`
-        properties:
-          display:
-            description: |
-              Thumbnail urls of product image (front) adapted to display on product page
-            type: object
-            $ref: "image_urls.yaml"
-          small:
-            description: |
-              Thumbnail urls of product image (front) adapted to display on product list page
-            type: object
-            $ref: "image_urls.yaml"
-          thumb:
-            description: |
-              Thumbnail urls of product image (front) in smallest format
-            type: object
-            $ref: "image_urls.yaml"
+        $ref: "./image_urls.yaml#/components/schemas/SelectedImage"
+
     patternProperties:
       "(?<image_type>front|packaging|ingredients|nutrition|other)":
         description: |

docs/api/ref/schemas/product_tags.yaml

@@ -97,7 +97,10 @@ properties:
     type: array
     items:
       type: string
-    example: ["2016-03-11", "2016-03", "2016"]
+    examples:
+      - - "2016-03-11"
+        - "2016-03"
+        - "2016"
 
   manufacturing_places:
     type: string
@@ -106,8 +109,7 @@ properties:
   manufacturing_places_tags:
     type: array
     items:
-      type: object
-      title: manufacturing_places_tag
+      type: "string"
   nova_groups_tags:
     type: array
     items: