From 2607b4f0b60e098d66b85dfd6ee9e5eb7712f83f Mon Sep 17 00:00:00 2001
From: dimaananskyi <dmytro@redocly.com>
Date: Thu, 29 Aug 2024 19:16:28 +0300
Subject: [PATCH] chore: document requestBody-replacements-unique rule

---
 docs/rules/arazzo/parameters-unique.md        |  4 +-
 .../arazzo/requestBody-replacements-unique.md | 87 +++++++++++++++++++
 docs/rules/recommended.md                     |  1 +
 3 files changed, 89 insertions(+), 3 deletions(-)
 create mode 100644 docs/rules/arazzo/requestBody-replacements-unique.md

diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md
index 391db8ee89..40f30feaee 100644
--- a/docs/rules/arazzo/parameters-unique.md
+++ b/docs/rules/arazzo/parameters-unique.md
@@ -36,7 +36,7 @@ style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px
 
 ## API design principles
 
-A list of `parameters` that are applicable for step or all steps described under workflow should not be duplicated to avoid shallow parameter override.
+A list of `parameters` that are applicable to step or all steps described under workflow should not be duplicated to avoid shadow parameter override.
 
 ## Configuration
 
@@ -88,8 +88,6 @@ workflows:
         value: Main Og==
 ```
 
-## Related rules
-
 ## Resources
 
 - [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/parameters-unique.ts)
diff --git a/docs/rules/arazzo/requestBody-replacements-unique.md b/docs/rules/arazzo/requestBody-replacements-unique.md
new file mode 100644
index 0000000000..7d7465c1d5
--- /dev/null
+++ b/docs/rules/arazzo/requestBody-replacements-unique.md
@@ -0,0 +1,87 @@
+---
+slug: /docs/cli/rules/arazzo/requestBody-replacements-unique
+---
+
+# requestBody-replacements-unique
+
+Requires the `replacements` of the `requestBody` object to be unique.
+
+| ARAZZO | Compatibility |
+| ------ | ------------- |
+| 1.0.0  | ✅            |
+
+```mermaid
+flowchart TD
+
+Root ==> workflows --> workflow --> steps --> step --> requestBody --> replacements
+
+style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px
+```
+
+## API design principles
+
+A list of locations and values to set within a payload must not have duplicates that might result in content override.
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+arazzoRules:
+  requestBody-replacements-unique: error
+```
+
+## Examples
+
+Given the following configuration:
+
+```yaml
+arazzoRules:
+  requestBody-replacements-unique: error
+```
+
+Example of an **incorrect** license:
+
+```yaml Object example
+workflows:
+  - workflowId: events-crud
+    steps:
+      - stepId: create-event
+        operationPath: $sourceDescriptions.museum-api#/paths/~1special-events/post
+        requestBody:
+          payload:
+            name: 'Mermaid Treasure Identification and Analysis'
+            description: 'Identify and analyze mermaid treasures'
+          replacements:
+            - target: name
+              value: 'new name'
+            - target: name
+              value: 'another name'
+```
+
+Example of a **correct** license:
+
+```yaml Object example
+workflows:
+  - workflowId: events-crud
+    steps:
+      - stepId: create-event
+        operationPath: $sourceDescriptions.museum-api#/paths/~1special-events/post
+        requestBody:
+          payload:
+            name: 'Mermaid Treasure Identification and Analysis'
+            description: 'Identify and analyze mermaid treasures'
+          replacements:
+            - target: name
+              value: 'new name'
+            - target: description
+              value: 'another description'
+```
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/requestBody-replacements-unique.ts)
diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md
index 0d80fae9f5..f6038adb1e 100644
--- a/docs/rules/recommended.md
+++ b/docs/rules/recommended.md
@@ -44,6 +44,7 @@ Warnings:
 - [tag-description](./tag-description.md)
 - [version-enum](./spot/version-enum.md)
 - [parameters-not-in-body](./spot/parameters-not-in-body.md)
+- [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md)
 
 ## Recommended strict ruleset