docs: Improved descriptions and schema adjustments for API references (…

…#10976)  ### What This pull request updates the API reference documentation files (docs/api/ref/schemas/**/*.yaml) to: - Improve clarity and detail by adding descriptions and comments to properties and references. - Address potential issues related to rapidoc and generator errors. - Make adjustments to schema definitions for better accuracy. - Added recursive references for Ingredient and Nutrient schemas in api.yml to fix generator errors. - Reorganized the structure of the image.yaml, image_role.yaml, image_urls.yaml, nutrients.yaml, product_base.yaml, product_ecoscore.yaml, product_extended.yaml, and product_tags.yaml files for better clarity and maintainability. - Updated pattern properties and refactored the structure of these YAML files to ensure consistency and correctness. We believe these changes will enhance the usability and understanding of the API reference for developers. Please review the changes and let us know if you have any feedback. ### SCREENSHOT ![image](https://github.com/user-attachments/assets/9837bcaa-0893-4aaa-aac9-692f998345d9) --------- Co-authored-by: Stéphane Gigandet <[email protected]>
openfoodfacts · Nov 8, 2024 · eeefdf0 · eeefdf0
1 parent 8a40a64
commit eeefdf0
Show file tree

Hide file tree

Showing 10 changed files with 127 additions and 112 deletions.
diff --git a/docs/api/ref/api.yml b/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:

diff --git a/docs/api/ref/schemas/image.yaml b/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.
diff --git a/docs/api/ref/schemas/image_role.yaml b/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"

diff --git a/docs/api/ref/schemas/image_urls.yaml b/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"
diff --git a/docs/api/ref/schemas/nutrients.yaml b/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"
diff --git a/docs/api/ref/schemas/product_base.yaml b/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: |

diff --git a/docs/api/ref/schemas/product_ecoscore.yaml b/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:

diff --git a/docs/api/ref/schemas/product_extended.yaml b/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

diff --git a/docs/api/ref/schemas/product_images.yaml b/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: |

diff --git a/docs/api/ref/schemas/product_tags.yaml b/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: