docs: Improve api def - tested ts client generation

[shinjigi]

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:

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

client_generation.mp4

Related issue(s) and discussion

• Fixes/RelatedTo:
  OpenAPISpec is not a valid 3.1.0 openAPI-Spec #8039
  docs: Make api.yml a valid OpenAPI-3.1.0-Spec #8042

[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

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 49.11%. Comparing base (dc04d18) to head (824ca62).
Report is 708 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10913      +/-   ##
==========================================
- Coverage   49.54%   49.11%   -0.44%     
==========================================
  Files          67       77      +10     
  Lines       20650    22197    +1547     
  Branches     4980     5306     +326     
==========================================
+ Hits        10231    10902     +671     
- Misses       9131     9963     +832     
- Partials     1288     1332      +44     

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