From a7df0c431986ee618ef49fbf3d6aff8d158c5ad9 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Tue, 4 Feb 2025 13:05:45 -0500 Subject: [PATCH 1/7] docs(all): clarifies what is overridden on a per-api basis --- docs/configuration/apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/apis.md b/docs/configuration/apis.md index 7c1160633b..f661adbb7e 100644 --- a/docs/configuration/apis.md +++ b/docs/configuration/apis.md @@ -9,7 +9,7 @@ For every API listed in the object, you must provide the path to the OpenAPI des If `rules`, `decorators`, or `preprocessors` aren't defined for an API, root settings are used. If `rules`, `decorators`, or `preprocessors` are defined for an API, its settings apply together with the root configuration. -If per-API and root settings modify the same properties, per-API settings overrides root settings. +If per-API `rules`, `decorators`, or `preprocessors` and root settings modify the same properties, per-API `rules`, `decorators`, and `preprocessors` override root settings. ## Patterned properties From 6738a68c4581ca538e61145117608945a713ee68 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Tue, 4 Feb 2025 17:09:50 -0500 Subject: [PATCH 2/7] docs(all): adds first-level properties wording --- docs/configuration/apis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/apis.md b/docs/configuration/apis.md index f661adbb7e..24ef709ed1 100644 --- a/docs/configuration/apis.md +++ b/docs/configuration/apis.md @@ -8,8 +8,8 @@ Every `name@version` combination listed in the object must be unique. For every API listed in the object, you must provide the path to the OpenAPI description using the `root` property. If `rules`, `decorators`, or `preprocessors` aren't defined for an API, root settings are used. -If `rules`, `decorators`, or `preprocessors` are defined for an API, its settings apply together with the root configuration. -If per-API `rules`, `decorators`, or `preprocessors` and root settings modify the same properties, per-API `rules`, `decorators`, and `preprocessors` override root settings. +If `rules`, `decorators`, or `preprocessors` are defined for an API, its first-level properties apply together with the root configuration. +If per-API `rules`, `decorators`, or `preprocessors` and root settings modify the same first-level properties, per-API `rules`, `decorators`, and `preprocessors` override root settings. ## Patterned properties From 2c41b7d114eae9ee1e19c3d91fbcf6b30e26a468 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Wed, 5 Feb 2025 12:26:07 -0500 Subject: [PATCH 3/7] docs(all): updates based on review --- docs/configuration/apis.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/configuration/apis.md b/docs/configuration/apis.md index 24ef709ed1..d9b81afb9f 100644 --- a/docs/configuration/apis.md +++ b/docs/configuration/apis.md @@ -8,8 +8,33 @@ Every `name@version` combination listed in the object must be unique. For every API listed in the object, you must provide the path to the OpenAPI description using the `root` property. If `rules`, `decorators`, or `preprocessors` aren't defined for an API, root settings are used. -If `rules`, `decorators`, or `preprocessors` are defined for an API, its first-level properties apply together with the root configuration. -If per-API `rules`, `decorators`, or `preprocessors` and root settings modify the same first-level properties, per-API `rules`, `decorators`, and `preprocessors` override root settings. +If `rules`, `decorators`, or `preprocessors` are defined for an API, they apply together with the root configuration. +If per-API `rules`, `decorators`, or `preprocessors` and root settings modify the same properties, per-API `rules`, `decorators`, and `preprocessors` override root settings. + +For example, if you include the same `decorator` at the root level and for a specific API, but with different properties, only the properties applied to the specific API will be applied to that API. + +So if you have the following `redocly.yaml` configuration, adding `decorator-one` and `decorator-two` at the root level and applying `decorator-one` to the `override@v1` API: + +```yaml +decorators: + decorator-one: + property-one: 1 + property-two: 2 + decorator-two: + property-three: 3 + property-four: 4 + +apis: + override@v1: + decorators: + decorator-one: + property-five: 5 +``` + +Only `property-five` is applied to `decorator-one` for the `override@v2` API, and both `property-three` and `property-four` are applied for `decorator-two`. + +For all other APIs, not including the `override@v2` API, `property-one` and `property-two` are applied to `decorator-one` and `property-three` and `property-four` are applied to `decorator-two`. + ## Patterned properties From eb46b5128a9fd79bcaf41418d021ec22860cf064 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Wed, 5 Feb 2025 15:43:08 -0500 Subject: [PATCH 4/7] docs(all): updates based on review --- docs/configuration/apis.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/configuration/apis.md b/docs/configuration/apis.md index d9b81afb9f..f5e38db27a 100644 --- a/docs/configuration/apis.md +++ b/docs/configuration/apis.md @@ -11,29 +11,30 @@ If `rules`, `decorators`, or `preprocessors` aren't defined for an API, root set If `rules`, `decorators`, or `preprocessors` are defined for an API, they apply together with the root configuration. If per-API `rules`, `decorators`, or `preprocessors` and root settings modify the same properties, per-API `rules`, `decorators`, and `preprocessors` override root settings. -For example, if you include the same `decorator` at the root level and for a specific API, but with different properties, only the properties applied to the specific API will be applied to that API. +For example, if you include the same `decorator` at the root level and for a specific API, but with different properties, the API-level settings replace the root ones. -So if you have the following `redocly.yaml` configuration, adding `decorator-one` and `decorator-two` at the root level and applying `decorator-one` to the `override@v1` API: +So if you have the following `redocly.yaml` configuration, adding `filter-in` and `plugin/change-title` at the root level and applying `plugin/change-title` with a different `title` property to the `storefront@latest` API: ```yaml decorators: - decorator-one: - property-one: 1 - property-two: 2 - decorator-two: - property-three: 3 - property-four: 4 + filter-in: + property: x-products + value: + - Core + plugin/change-title: + title: All APIs + apis: - override@v1: + storefront@latest: decorators: - decorator-one: - property-five: 5 + plugin/change-title: + title: Storefront APIs ``` -Only `property-five` is applied to `decorator-one` for the `override@v2` API, and both `property-three` and `property-four` are applied for `decorator-two`. +The `plugin/change-title` decorator with the "Storefront APIs" `title` property is applied to the `storefront@latest` API, and the `filter-in` decorator is also applied to the `storefront@latest` API. -For all other APIs, not including the `override@v2` API, `property-one` and `property-two` are applied to `decorator-one` and `property-three` and `property-four` are applied to `decorator-two`. +For all other APIs, not including the `storefront@latest` API, `filter-in` and `plugin/change-title` with the "Core" `title` property are applied. ## Patterned properties From 64e79749823bdb9ffe619e797ac774d814f6193d Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Thu, 6 Feb 2025 08:50:05 -0500 Subject: [PATCH 5/7] docs(all): fixes lint issue --- docs/configuration/apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/apis.md b/docs/configuration/apis.md index f5e38db27a..2c973effde 100644 --- a/docs/configuration/apis.md +++ b/docs/configuration/apis.md @@ -21,7 +21,7 @@ decorators: property: x-products value: - Core - plugin/change-title: + plugin/change-title: title: All APIs From 3daa7451207c76cd3c1645f4e012778e7a013f7e Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Thu, 6 Feb 2025 11:08:23 -0500 Subject: [PATCH 6/7] docs(all): fixes prettier issue --- docs/configuration/apis.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/configuration/apis.md b/docs/configuration/apis.md index 2c973effde..20cdb0cd2b 100644 --- a/docs/configuration/apis.md +++ b/docs/configuration/apis.md @@ -23,7 +23,7 @@ decorators: - Core plugin/change-title: title: All APIs - + apis: storefront@latest: @@ -36,7 +36,6 @@ The `plugin/change-title` decorator with the "Storefront APIs" `title` property For all other APIs, not including the `storefront@latest` API, `filter-in` and `plugin/change-title` with the "Core" `title` property are applied. - ## Patterned properties {% json-schema From 0e531ec3ee2da1fdf36edb5760d1b849f287968a Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sat, 8 Feb 2025 10:59:40 -0500 Subject: [PATCH 7/7] docs(all): updates based on review --- docs/configuration/apis.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/configuration/apis.md b/docs/configuration/apis.md index 20cdb0cd2b..f63f73cd58 100644 --- a/docs/configuration/apis.md +++ b/docs/configuration/apis.md @@ -9,7 +9,7 @@ For every API listed in the object, you must provide the path to the OpenAPI des If `rules`, `decorators`, or `preprocessors` aren't defined for an API, root settings are used. If `rules`, `decorators`, or `preprocessors` are defined for an API, they apply together with the root configuration. -If per-API `rules`, `decorators`, or `preprocessors` and root settings modify the same properties, per-API `rules`, `decorators`, and `preprocessors` override root settings. +If the same `rules`, `decorators`, or `preprocessors` are defined on `apis` and the root level, per-API `rules`, `decorators`, and `preprocessors` override the root ones. For example, if you include the same `decorator` at the root level and for a specific API, but with different properties, the API-level settings replace the root ones. @@ -23,6 +23,7 @@ decorators: - Core plugin/change-title: title: All APIs + extraProperty: This property will be ignored at the per-API level. apis: @@ -32,9 +33,9 @@ apis: title: Storefront APIs ``` -The `plugin/change-title` decorator with the "Storefront APIs" `title` property is applied to the `storefront@latest` API, and the `filter-in` decorator is also applied to the `storefront@latest` API. +The `plugin/change-title` decorator with the "Storefront APIs" `title` property is applied to the `storefront@latest` API with the value `Storefront APIs`, and the `filter-in` decorator is also applied to the `storefront@latest` API. -For all other APIs, not including the `storefront@latest` API, `filter-in` and `plugin/change-title` with the "Core" `title` property are applied. +For all other APIs, not including the `storefront@latest` API, `filter-in` and `plugin/change-title` with the "Core" `title` and `extraProperty` properties are applied. ## Patterned properties