docs: Improved descriptions and schema adjustments for API references

[shinjigi]

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

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 49.03%. Comparing base (dc04d18) to head (649c68a).
Report is 749 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10976      +/-   ##
==========================================
- Coverage   49.54%   49.03%   -0.51%     
==========================================
  Files          67       77      +10     
  Lines       20650    22239    +1589     
  Branches     4980     5316     +336     
==========================================
+ Hits        10231    10906     +675     
- Misses       9131    10000     +869     
- Partials     1288     1333      +45     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stephanegigandet]

Thank you @shinjigi ! I added a couple of suggestions.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud