docs(all): clarifies what is overridden on a per-api basis (#1882)

* docs(all): clarifies what is overridden on a per-api basis

* docs(all): adds first-level properties wording

* docs(all): updates based on review

* docs(all): updates based on review

* docs(all): fixes lint issue

* docs(all): fixes prettier issue

* docs(all): updates based on review

Author: HCloward

docs/configuration/apis.md

@@ -8,8 +8,34 @@ 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 and root settings modify the same properties, per-API settings overrides root settings.
+If `rules`, `decorators`, or `preprocessors` are defined for an API, they apply together with the root configuration.
+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.
+
+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:
+  filter-in:
+    property: x-products
+    value:
+      - Core
+  plugin/change-title:
+    title: All APIs
+    extraProperty: This property will be ignored at the per-API level.
+
+
+apis:
+  storefront@latest:
+    decorators:
+      plugin/change-title:
+        title: Storefront APIs
+```
+
+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` and `extraProperty` properties are applied.
 
 ## Patterned properties