From b2f2ca9ca39151e28176519ca9c81ca182ca799b Mon Sep 17 00:00:00 2001 From: Shinjigi Date: Tue, 19 Nov 2024 10:58:54 +0100 Subject: [PATCH] fix: apidoc openApi ecoscore mapping (#11009) - [x] PR title is prefixed by one of the following: feat, fix, docs, style, refactor, test, build, ci, chore, revert, l10n, taxonomy - [x] Code is well documented - [x] Include unit tests for new functionality - [x] Code passes GitHub workflow checks in your branch - [x] If you have multiple commits please combine them into one commit by squashing them. - [x] Read and understood the contribution guidelines ### What This PR introduces several improvements to the API documentation and schema organization: 1. **New Schema File for Country Codes** - Created a dedicated `country-code.yaml` file to centralize country code definitions - Introduced reusable `CountryCode` enum with all supported country codes - Added `CountryValues` schema to standardize country-to-number mappings - Commented out pattern properties in favor of generator-friendly alternatives 2. **Product Ecoscore Schema Improvements** - Refactored country-specific properties to use the new `CountryValues` schema - Added proper type handling for nullable integer fields (`transportation_score`) - Removed redundant pattern properties in favor of schema references - Enhanced type definitions for scores and values 3. **Packaging Schema Enhancements** - Added comprehensive examples for packaging properties - Added missing fields with proper examples: - `number_of_units` - `quantity_per_unit` and related fields - `recycling` - `weight_measured` 4. **Agribalyse Schema Updates** - Added `agribalyse_proxy_food_code` field - Added `agribalyse_food_code` field - Added `co2_agriculture` field The changes improve code organization, reduce duplication, and enhance compatibility with OpenAPI code generators while maintaining backward compatibility with existing data structures. ### Related issue(s) and discussion - Fixes #[ISSUE NUMBER] This refactoring improves schema maintainability and provides better type safety through proper enum definitions and standardized patterns for country-specific data. --- docs/api/ref/schemas/agribalyse.yaml | 2 + .../ref/schemas/ecoscore-country-code.yaml | 81 +++++++++++++++++++ docs/api/ref/schemas/product_ecoscore.yaml | 60 ++++++++------ 3 files changed, 120 insertions(+), 23 deletions(-) create mode 100644 docs/api/ref/schemas/ecoscore-country-code.yaml diff --git a/docs/api/ref/schemas/agribalyse.yaml b/docs/api/ref/schemas/agribalyse.yaml index c8c990a2a70c7..2da419fa2f616 100644 --- a/docs/api/ref/schemas/agribalyse.yaml +++ b/docs/api/ref/schemas/agribalyse.yaml @@ -1,5 +1,7 @@ type: object properties: + agribalyse_proxy_food_code: + type: string agribalyse_food_code: type: string co2_agriculture: diff --git a/docs/api/ref/schemas/ecoscore-country-code.yaml b/docs/api/ref/schemas/ecoscore-country-code.yaml new file mode 100644 index 0000000000000..c057e46816fa0 --- /dev/null +++ b/docs/api/ref/schemas/ecoscore-country-code.yaml @@ -0,0 +1,81 @@ +components: + schemas: + EcoscoreCountryCode: + type: string + enum: + [ + "ad", + "al", + "at", + "ax", + "ba", + "be", + "bg", + "ch", + "cy", + "cz", + "de", + "dk", + "dz", + "ee", + "eg", + "es", + "fi", + "fo", + "fr", + "gg", + "gi", + "gr", + "hr", + "hu", + "ie", + "il", + "im", + "is", + "it", + "je", + "lb", + "li", + "lt", + "lu", + "lv", + "ly", + "ma", + "mc", + "md", + "me", + "mk", + "mt", + "nl", + "no", + "pl", + "ps", + "pt", + "ro", + "rs", + "se", + "si", + "sj", + "sk", + "sm", + "sy", + "tn", + "tr", + "ua", + "uk", + "us", + "va", + "world", + "xk", + ] + # patternProperties not supported by generators + #patternProperties: + # (?\w\w): + # type: integer + EcoscoreCountryValues: + type: object + propertyNames: + $ref: "#/components/schemas/EcoscoreCountryCode" + additionalProperties: + type: number + default: 0 diff --git a/docs/api/ref/schemas/product_ecoscore.yaml b/docs/api/ref/schemas/product_ecoscore.yaml index d2cf9103c5a4e..aad79def03404 100644 --- a/docs/api/ref/schemas/product_ecoscore.yaml +++ b/docs/api/ref/schemas/product_ecoscore.yaml @@ -26,10 +26,16 @@ properties: title: adjustments_origin_of_ingredient_aggregated type: object properties: + epi_score: + type: string #TODO: should be integer origin: type: string percent: type: integer + transportation_score: + type: + - "null" + - "integer" epi_score: type: integer epi_value: @@ -42,31 +48,18 @@ properties: type: array items: type: string + transportation_score: + type: integer transportation_scores: - type: object - properties: - world: - type: integer - patternProperties: - (?\w\w): - type: integer + $ref: "./ecoscore-country-code.yaml#/components/schemas/EcoscoreCountryValues" + transportation_value: + type: integer transportation_values: - type: object - properties: - world: - type: integer - patternProperties: - (?\w\w): - type: integer - + $ref: "./ecoscore-country-code.yaml#/components/schemas/EcoscoreCountryValues" + value: + type: integer values: - type: object - properties: - world: - type: integer - patternProperties: - (?\w\w): - type: integer + $ref: "./ecoscore-country-code.yaml#/components/schemas/EcoscoreCountryValues" warning: type: string packaging: @@ -88,6 +81,24 @@ properties: type: string shape: type: string + number_of_units: + type: integer + examples: [1] + quantity_per_unit: + type: string + examples: ["33 cL"] + quantity_per_unit_unit: + type: string + examples: ["cl"] + quantity_per_unit_value: + type: number + examples: [33] + recycling: + type: string + examples: ["en:recycle-in-sorting-bin"] + weight_measured: + type: number + examples: [12.08] score: type: integer value: @@ -99,7 +110,10 @@ properties: properties: labels: type: array - example: "vegan, fat free, Kosher" + examples: + - - vegan + - fat free + - Kosher items: type: string value: