fix: add unit to output of /cgi/nutrients.pl (#9751)

with API documentation and tests.

cgi/nutrients.pl

@@ -63,6 +63,10 @@
 	if (defined $name) {
 		$current_ref->{name} = $name;
 	}
+	my $unit = get_property("nutrients", "zz:$onid", "unit:en") // 'g';
+	if (defined $unit) {
+		$current_ref->{unit} = $unit;
+	}
 
 	my $prefix_length = 0;
 	if ($nid =~ s/^--//g) {

docs/api/ref/api-v3.yml

@@ -38,16 +38,8 @@ paths:
           schema:
             type: string
             example: '3017620422003'
-        - schema:
-            type: string
-          in: query
-          name: lc
-          description: '2 letter code of the language of the interface. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the country of the user (passed through the cc field or inferred by the IP address).'
-        - schema:
-            type: string
-          in: query
-          name: cc
-          description: '2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.'
+        - $ref: '#/components/parameters/cc'
+        - $ref: '#/components/parameters/lc'
         - schema:
             type: string
           in: query
@@ -265,23 +257,14 @@ paths:
         If a string is passed, an additional sort is done to put first suggestions that start with the string, followed by suggestions with a word that start with the string, and then suggestions that contain the string anywhere.
       parameters:
         - $ref: ./api.yml#/components/parameters/tagtype
-        - schema:
-            type: string
-            example: en
-          in: query
-          name: lc
-          description: 2 letter code of the language used for suggestions and for matching the input string
+        - $ref: '#/components/parameters/cc'
+        - $ref: '#/components/parameters/lc'
         - schema:
             type: string
             example: pe
           in: query
           name: string
           description: 'Optional string used to filter suggestions (useful for autocomplete).  If passed, suggestions starting with the string will be returned first, followed by suggestions matching the string at the beginning of a word, and suggestions matching the string inside a word.'
-        - schema:
-            type: string
-          in: query
-          name: cc
-          description: '2 letter country code, used to return popular packaging shapes and materials for products sold in the country'
         - schema:
             type: string
             example: yougurts
@@ -306,6 +289,8 @@ paths:
           description: Alias for the "string" parameter provided for backward compatibility. "string" takes precedence.
   '/api/v3/tag/{tagtype}/{tag_or_tagid}':
     parameters:
+      - $ref: '#/components/parameters/cc'
+      - $ref: '#/components/parameters/lc'    
       - schema:
           type: string
           example: categories
@@ -364,6 +349,32 @@ paths:
 
         Categories:
         - Packaging stats for a category
+components:
+  parameters:
+    cc:
+      schema:
+        type: string
+        example: 'us'
+      in: query
+      name: cc
+      required: false
+      description: '2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.'
+    lc:
+      schema:
+        type: string
+        example: 'fr'
+      in: query
+      name: lc
+      required: false
+      description: '2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request.'
+    code:
+      schema:
+        type: string
+        example: '4251105501381'
+      in: query
+      name: code
+      description: Barcode of the product
+      required: true
 tags:
   - name: Read Requests
   - name: Write Requests

docs/api/ref/api.yml

@@ -295,6 +295,24 @@ paths:
         all packaging_shapes containing "fe" will be returned.
         This is useful if you have a search in your application,
         for a specific product field.
+  /cgi/nutrients.pl:
+    get:
+      summary: Get a nested list of nutrients that can be displayed in the nutrition facts table for a specific country and language
+      tags:
+        - Read Requests
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: ./responses/get_nutrients.yaml
+      operationId: get-cgi-nutrients.pl
+      parameters:
+        - $ref: '#/components/parameters/cc'
+        - $ref: '#/components/parameters/lc'
+      description: |
+        Used to display the nutrition facts table of a product, or to display a form to input those nutrition facts.
 components:
   schemas:
     "Product-Base":
@@ -327,6 +345,22 @@ components:
       in: query
       name: id
       required: true
+    cc:
+      schema:
+        type: string
+        example: 'us'
+      in: query
+      name: cc
+      required: false
+      description: '2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.'
+    lc:
+      schema:
+        type: string
+        example: 'fr'
+      in: query
+      name: lc
+      required: false
+      description: '2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request.'
     code:
       schema:
         type: string
@@ -363,7 +397,6 @@ components:
       in: query
       name: angle
       required: true
-
     sort_by:
       schema:
         type: string

docs/api/ref/responses/get_nutrients.yaml

@@ -0,0 +1 @@
+$ref: ../schemas/nutrients.yaml

docs/api/ref/schemas/nutrient_unit.yaml

@@ -0,0 +1,21 @@
+description: |
+  The unit in which the nutrient for 100g or per serving is measured.
+
+  The possible values depends on the nutrient.
+
+  * `g` for grams
+  * `mg` for milligrams
+  * `μg` for micrograms
+  * `cl` for centiliters
+  * `ml` for mililiters
+  * `dv` for recommended daily intakes (aka [Dietary Reference Intake](https://en.wikipedia.org/wiki/Dietary_Reference_Intake))
+  * `% vol` for percentage per volume (e.g. alcohol vol per 100 ml)
+  * `%` for percentage
+
+  🤓 code: see the [Units module][units-module],
+  and [Food:default_unit_for_nid function][default-unit]
+
+  [units-module]: https://openfoodfacts.github.io/openfoodfacts-server/dev/ref-perl-pod/ProductOpener/Units.html
+  [default-unit]: https://openfoodfacts.github.io/openfoodfacts-server/dev/ref-perl-pod/ProductOpener/Food.html#default_unit_for_nid_(_%24nid)
+type: string
+enum: ['g','mg','μg','cl','ml','dv','% vol','%']

docs/api/ref/schemas/nutrients.yaml

@@ -0,0 +1,26 @@
+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:
+      description: |
+        Sub-nutrients (e.g. saturated-fat is a sub-nutrient of fat).
+      # self recursive
+      $ref: "#/"

tests/integration/api_cgi_nutrients.t

@@ -0,0 +1,42 @@
+#!/usr/bin/perl -w
+
+use ProductOpener::PerlStandards;
+
+use Test::More;
+use ProductOpener::APITest qw/:all/;
+use ProductOpener::Test qw/:all/;
+use ProductOpener::TestDefaults qw/:all/;
+
+use File::Basename "dirname";
+
+use Storable qw(dclone);
+
+remove_all_users();
+
+remove_all_products();
+
+wait_application_ready();
+
+# Note: expected results are stored in json files, see execute_api_tests
+my $tests_ref = [
+	{
+		test_case => 'default',
+		method => 'GET',
+		path => '/cgi/nutrients.pl',
+	},
+	{
+		test_case => 'fr-fr',
+		method => 'GET',
+		path => '/cgi/nutrients.pl?cc=fr&lc=fr',
+	},
+	{
+		test_case => 'en-us',
+		method => 'GET',
+		path => '/cgi/nutrients.pl?cc=us&lc=en',
+		expected_status_code => 200,
+	},
+];
+
+execute_api_tests(__FILE__, $tests_ref);
+
+done_testing();