From b3f89f38546d19cde8283d7eeaf55b47f7209b14 Mon Sep 17 00:00:00 2001
From: DmitryAnansky <dmytro@redocly.com>
Date: Fri, 18 Oct 2024 17:20:12 +0300
Subject: [PATCH] chore: add sourceDescriptions-not-empty rule docs

---
 .../arazzo/sourceDescriptions-not-empty.md    | 93 +++++++++++++++++++
 docs/rules/built-in-rules.md                  |  1 +
 2 files changed, 94 insertions(+)
 create mode 100644 docs/rules/arazzo/sourceDescriptions-not-empty.md

diff --git a/docs/rules/arazzo/sourceDescriptions-not-empty.md b/docs/rules/arazzo/sourceDescriptions-not-empty.md
new file mode 100644
index 000000000..cfa14beaf
--- /dev/null
+++ b/docs/rules/arazzo/sourceDescriptions-not-empty.md
@@ -0,0 +1,93 @@
+# sourceDescriptions-not-empty
+
+The Source Description must have at least one entry.
+
+| Arazzo | Compatibility |
+| ------ | ------------- |
+| 1.0.0  | ✅            |
+
+## API design principles
+
+According to the Arazzo spec `sourceDescriptions` is required and the list must have at least one entry.
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+rules:
+  sourceDescriptions-not-empty: error
+```
+
+## Examples
+
+Given the following configuration:
+
+```yaml
+rules:
+  sourceDescriptions-not-empty: error
+```
+
+Example of an **incorrect** usage:
+
+```yaml Incorrect example
+arazzo: '1.0.0'
+info:
+  title: Cool API
+  version: 1.0.0
+  description: A cool API
+sourceDescriptions: []
+workflows:
+  - workflowId: get-museum-hours
+      description: This workflow demonstrates how to get the museum opening hours and buy tickets.
+      parameters:
+      - in: header
+          name: Authorization
+          value: Basic Og==
+      steps:
+      - stepId: get-museum-hours
+          description: >-
+            Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description.
+          operationId: $sourceDescriptions.museum-api.getMuseumHours
+          successCriteria:
+          - condition: $statusCode == 200
+```
+
+Example of a **correct** usage:
+
+```yaml Correct example
+arazzo: '1.0.0'
+info:
+  title: Cool API
+  version: 1.0.0
+  description: A cool API
+sourceDescriptions:
+  - name: museum-api
+    type: openapi
+    url: openapi.yaml
+  - name: another-api
+    type: openapi
+    url: openapi.yaml
+workflows:
+  - workflowId: get-museum-hours
+    description: This workflow demonstrates how to get the museum opening hours and buy tickets.
+    parameters:
+      - in: header
+        name: Authorization
+        value: Basic Og==
+    steps:
+      - stepId: get-museum-hours
+        description: >-
+          Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description.
+        operationId: $sourceDescriptions.museum-api.getMuseumHours
+        successCriteria:
+          - condition: $statusCode == 200
+```
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/sourceDescriptions-not-empty.ts)
diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md
index a177b0b94..5da31a89b 100644
--- a/docs/rules/built-in-rules.md
+++ b/docs/rules/built-in-rules.md
@@ -128,6 +128,7 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica
 - [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md): the `onSuccess` actions of the `step` object must be unique
 - [workflow-dependsOn](./arazzo/workflow-dependsOn.md): the items in the `workflow` `dependsOn` property must exist and be unique
 - [workflowId-unique](./arazzo/workflowId-unique.md): the `workflowId` property must be unique across all workflows
+- [sourceDescriptions-not-empty](./arazzo/sourceDescriptions-not-empty.md): the `sourceDescriptions` must be defined and the list must have at least one entry.
 
 ### Spot