docs: Improve api def - tested ts client generation (#10913)

feat(api): improve OpenAPI schema consistency and structure

### What
This pull request enhances the consistency and structure of OpenAPI
schemas in the Open Food Facts project. The main changes include:

- Added missing titles to response and request schemas for better
identification
- Standardized schema references using #/components/schemas/ for
improved consistency
- Removed unnecessary x-stoplight metadata
- Fixed inconsistencies in data types and enums
- Improved descriptions and examples in various schemas
- Restructured the image_role schema for better organization
- Updated the product schema to use centralized component references

These changes improve the readability, maintainability, and consistency
of the API definition, making it easier for developers to use and
integrate.

The updated schema has been tested with the following OpenAPI generators
and tools:

- OpenAPI Generator:
  - typescript-fetch
  - typescript
  - javascript
- @hey-api/openapi-ts
- Swagger Editor (editor-next.swagger.io)

The primary configuration used for testing was:

```yaml
generatorName: typescript-fetch
outputDir: ./clients/ts-fetch
inputSpec: ./fork-shinjigi-4pullrequest-api-ref/api.yml
verbose: false
additionalProperties:
  npmName: "@iside/ec-open-food-facts-client-ts-fetch"
  npmVersion: "1.122.0"
  npmRepository: "http://"
  snapshot: false
  supportsES6: false
  modelPropertyNaming: "original"
  enumPropertyNaming: "original"
  paramNaming: "original"
enablePostProcessFile: true
modelNameMappings:
  ingredient_1: Ingredient
  product_extended_owner_fields_1: ProductExtendedOwnerFields
  product_extended_owner_fields_1_additionalProperties: ProductExtendedOwnerFieldsAdditionalProperties
  product_ecoscore_data_1: ProductEcoscoreData
globalProperties:
  debugOpenAPI: true
```

### Screenshot

![graph](https://github.com/user-attachments/assets/05da6b7c-ad85-4217-bbf3-57339fd6d883)


https://github.com/user-attachments/assets/61f50394-8992-4b8e-bd9c-76c8c138390a



### Related issue(s) and discussion
- Fixes/RelatedTo:
#8039 
#8042

docs/api/ref/api.yml

@@ -81,12 +81,13 @@ paths:
           content:
             application/json:
               schema:
+                title: get_product_by_barcode_knowledge_panels_response
                 allOf:
                   - $ref: ./responses/get_product_by_barcode_base.yaml
                   - type: object
                     properties:
                       product:
-                        $ref: ./schemas/product_knowledge_panels.yaml
+                        $ref: "#/components/schemas/Product-Knowledge-Panels"
       description: |
         Knowledge panels gives high leve informations about a product,
         ready to display.
@@ -196,6 +197,7 @@ paths:
           content:
             application/json:
               schema:
+                title: unselect_a_photo_response
                 type: object
                 properties:
                   status:
@@ -403,6 +405,7 @@ paths:
           content:
             application/json:
               schema:
+                title: get_attribute_groups_response
                 $ref: ./responses/get_attribute_groups.yaml
       parameters:
         - $ref: "#/components/parameters/lc"
@@ -432,18 +435,22 @@ components:
       $ref: ./schemas/product_misc.yaml
     "Product-Tags":
       $ref: ./schemas/product_tags.yaml
-    "Product-Nutrition":
-      $ref: ./schemas/product_nutrition.yaml
-    "Product-Ingredients":
-      $ref: ./schemas/product_ingredients.yaml
     "Product-Images":
       $ref: ./schemas/product_images.yaml
     "Product-Eco-Score":
       $ref: ./schemas/product_ecoscore.yaml
+    "Product-Ingredients":
+      $ref: ./schemas/product_ingredients.yaml
+    "Product-Nutrition":
+      $ref: ./schemas/product_nutrition.yaml
+    "Product-Quality":
+      $ref: ./schemas/product_quality.yaml
+    "Product-Data-Quality":
+      $ref: ./schemas/product_knowledge_panels.yaml
+    "Product-Extended":
+      $ref: ./schemas/product_extended.yaml
     "Product-Metadata":
       $ref: ./schemas/product_meta.yaml
-    "Product-Data-Quality":
-      $ref: ./schemas/product_quality.yaml
     "Product-Knowledge-Panels":
       $ref: ./schemas/product_knowledge_panels.yaml
     "Product-Attribute-Groups":

docs/api/ref/requestBodies/unselect_a_photo.yaml

@@ -1,9 +1,10 @@
 type: object
+title: unselect_a_photo_request
 properties:
   code:
     type: string
     description: code of the product
-    example: '4251105501381'
+    example: "4251105501381"
   id:
     type: string
     description: image field (image id) of the photo to unselect

docs/api/ref/responses/add_or_edit_a_product.yaml

@@ -1,8 +1,9 @@
 type: object
+title: add_or_edit_a_product_response
 properties:
   status_verbose:
     type: string
     example: fields saved
   status:
     type: integer
-    example: 1
+    example: 1

docs/api/ref/responses/add_photo_to_existing_product.yaml

@@ -1,4 +1,5 @@
 #TODO: Describe these response fields
+title: add_photo_to_existing_product_response
 type: object
 properties:
   files:
@@ -11,7 +12,7 @@ properties:
           example: /product/3017620422003/nutella-ferrero
         filename:
           type: string
-          example: ''
+          example: ""
         name:
           type: string
           example: Nutella - Ferrero - 400g
@@ -20,7 +21,7 @@ properties:
           example: /images/products/301/762/042/2003/123.100.jpg
         code:
           type: string
-          example: '3017620422003'
+          example: "3017620422003"
   image:
     type: object
     properties:
@@ -44,4 +45,4 @@ properties:
     example: front_en
   code:
     type: string
-    example: '3017620422003'
+    example: "3017620422003"

docs/api/ref/responses/change_ref_properties.yaml

@@ -1,8 +1,9 @@
 type: object
+title: change_ref_properties_response
 properties:
   status_verbose:
     type: string
     example: fields saved
   status:
     type: integer
-    example: 1
+    example: 1

docs/api/ref/responses/get_attribute_groups.yaml

@@ -2,6 +2,7 @@ type: array
 description: |
   List of groups of attributes for personal search in a specific language.
 items:
+  title: attribute_group
   type: object
   properties:
     id:
@@ -15,6 +16,7 @@ items:
       description: |
         Attributes that are part of this group
       items:
+        title: attribute
         type: object
         properties:
           id:
@@ -35,11 +37,11 @@ items:
           default:
             type: string
             enum:
-            - "mandatory"
-            - "very_important"
-            - "important"
-            - "not_important"
+              - "mandatory"
+              - "very_important"
+              - "important"
+              - "not_important"
             description: Indicates the default setting for this attribute
           panel_id:
             type: string
-            description: Linked knowledge panel (optional)
+            description: Linked knowledge panel (optional)

docs/api/ref/responses/get_preferences.yaml

@@ -1,4 +1,5 @@
 type: array
+title: get_preferences_response
 description: |
   Rules to apply to compute personal ranking of a product,
   based upon the setting value of each attribute.
@@ -9,10 +10,10 @@ items:
       type: string
       description: id for the setting value
       enum:
-      - "not_important"
-      - "important"
-      - "very_important"
-      - "mandatory"
+        - "not_important"
+        - "important"
+        - "very_important"
+        - "mandatory"
     name:
       type: string
       description: name for the setting value, translated according to `lc` parameter

docs/api/ref/responses/get_product_by_barcode.yaml

@@ -1,8 +1,7 @@
-x-stoplight:
-  id: cfk5obotr63sa
 type: object
+title: get_product_by_barcode_response
 allOf:
   - $ref: ./get_product_by_barcode_base.yaml
   - properties:
       product:
-        $ref: ../schemas/product.yaml
+        $ref: ../schemas/product.yaml

docs/api/ref/responses/get_product_by_barcode_base.yaml

@@ -1,6 +1,5 @@
 type: object
-x-stoplight:
-  id: s4gz59htj4gc3
+title: get_product_by_barcode_base_response
 properties:
   code:
     type: string
@@ -11,5 +10,7 @@ properties:
       number starting with the 200 reserved prefix.
   status:
     type: integer
+    enum: [0, 1]
+    description: Return values based on ProductOpener/Display.pm analysis
   status_verbose:
     type: string

docs/api/ref/responses/ocr_on_product.yaml

@@ -1,4 +1,5 @@
 type: object
+title: ocr_on_product_response
 properties:
   status:
     type: integer

docs/api/ref/responses/response-status/response_status.yaml

@@ -1,8 +1,6 @@
 title: Response status
-x-stoplight:
-  id: 54bh0c5mejahn
 type: object
-description: 'A response object to describe if a READ or WRITE request was successful or not, and if there were errors or warnings, and what the impact of those errors or warnings was.'
+description: "A response object to describe if a READ or WRITE request was successful or not, and if there were errors or warnings, and what the impact of those errors or warnings was."
 examples:
   - status_id: success_with_errors
     result:
@@ -18,7 +16,7 @@ examples:
           lc_description: Les sucres (40g) sont plus élévés que les glucdes.
         field:
           id: nutriment.sugars
-          value: '40'
+          value: "40"
         impact:
           id: nutrients_not_updated
           name: Nutrients not updated
@@ -33,7 +31,7 @@ properties:
       - success_with_warnings
       - success_with_errors
       - failure
-    description: 'Overall status of the request: whether it failed or succeeded, with or without warnings or errors.'
+    description: "Overall status of the request: whether it failed or succeeded, with or without warnings or errors."
   result:
     type: object
     description: |-
@@ -48,10 +46,10 @@ properties:
         description: Name of the response result entry in English.
       lc_name:
         type: string
-        description: 'Name of the response result entry in the language specified in tags_lc, if supplied.'
+        description: "Name of the response result entry in the language specified in tags_lc, if supplied."
   warnings:
     type: array
-    description: 'List of warnings. Warnings are used to alert about something that may be wrong, but is not necessarily wrong (e.g. a nutrient value that is unexpectedly high).'
+    description: "List of warnings. Warnings are used to alert about something that may be wrong, but is not necessarily wrong (e.g. a nutrient value that is unexpectedly high)."
     items:
       $ref: ./warning-or-error.yaml
   errors:

docs/api/ref/responses/rotate_a_photo.yaml

@@ -1,6 +1,7 @@
 #TODO: Describe the response fields
 #TODO: Api review to sort this response in a particular order. It is not fixed.
 type: object
+title: rotate_a_photo_response
 properties:
   status:
     type: string
@@ -14,4 +15,3 @@ properties:
       display_url:
         type: string
         example: nutrition_fr.67.400.jpg
-

docs/api/ref/responses/search_for_products.yaml

@@ -1,4 +1,5 @@
 type: object
+title: search_for_products_response
 properties:
   count:
     type: integer

docs/api/ref/schemas/image.yaml

@@ -5,20 +5,16 @@ description: |
   "imgid" is an integer which is a sequential number unique to each picture.
 properties:
   sizes:
-    title: image_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:
-          description: |
-            properties of fullsize image
-            **TODO** explain how to compute name
-          $ref: ./image_size.yaml
+        $ref: ./image_size.yaml
     patternProperties:
-      '(?<image_size>100|400)':
+      "(?<image_size>100|400)":
         description: |
           properties of thumbnail of size `image_size`.
           **TODO** explain how to compute name
@@ -28,7 +24,7 @@ properties:
         type: string
   uploaded_t:
     type: string
-    example: '1457680652'
+    example: "1457680652"
     description: |
       The time the image was uploaded (as unix timestamp).
   uploader: