From 22fefbc7940bce54408f11883fd2c94e5bc5600c Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Fri, 8 Nov 2024 14:22:00 -0800
Subject: [PATCH] [8.x] [OpenAPI] Add redocly lint configuration (#199360)
 (#199554)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[OpenAPI] Add redocly lint configuration
(#199360)](https://github.com/elastic/kibana/pull/199360)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2024-11-08T20:07:55Z","message":"[OpenAPI]
Add redocly lint configuration
(#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","Feature:OAS","v8.16.0","backport:version","v8.17.0"],"number":199360,"url":"https://github.com/elastic/kibana/pull/199360","mergeCommit":{"message":"[OpenAPI]
Add redocly lint configuration
(#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199360","number":199360,"mergeCommit":{"message":"[OpenAPI]
Add redocly lint configuration
(#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65"}},{"branch":"8.16","label":"v8.16.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->
---
 oas_docs/README.md                    |  3 +-
 oas_docs/{ => linters}/.spectral.yaml |  0
 oas_docs/linters/redocly.yaml         | 52 +++++++++++++++++++++++++++
 oas_docs/makefile                     | 12 +++----
 4 files changed, 57 insertions(+), 10 deletions(-)
 rename oas_docs/{ => linters}/.spectral.yaml (100%)
 create mode 100644 oas_docs/linters/redocly.yaml

diff --git a/oas_docs/README.md b/oas_docs/README.md
index e37eefaed4851..3312bc60771e0 100644
--- a/oas_docs/README.md
+++ b/oas_docs/README.md
@@ -45,8 +45,7 @@ Besides the scripts in the `oas_docs/scripts` folder, there is an `oas_docs/make
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `api-docs`                 | Builds ESS Kibana OpenAPI bundle                                                                                                                                                                                   |
 | `api-docs-serverless`      | Builds Serverless Kibana OpenAPI bundle                                                                                                                                                                            |
-| `api-docs-lint`            | Lints built result bundles                                                                                                                                                                                         |
-| `api-docs-lint-errs`       | Lints built result bundles for errors                                                                                                                                                                              |
+| `api-docs-lint`            | Lints built result bundles              |
 | `api-docs-preview`         | Generates (ESS + Serverless) Kibana OpenAPI bundles preview                                                                                                                                                        |
 | `api-docs-overlay`         | Applies [overlays](https://docs.bump.sh/help/specification-support/overlays/) from `overlays` folder to the Kibana OpenAPI bundles and generate `*.new.yaml` files. Overlays help to fine tune the result bundles. |
 | `api-docs-overlay-preview` | Generates a preview for bundles produced by `api-docs-overlay`                                                                                                                                                     |
diff --git a/oas_docs/.spectral.yaml b/oas_docs/linters/.spectral.yaml
similarity index 100%
rename from oas_docs/.spectral.yaml
rename to oas_docs/linters/.spectral.yaml
diff --git a/oas_docs/linters/redocly.yaml b/oas_docs/linters/redocly.yaml
new file mode 100644
index 0000000000000..139a503ba856c
--- /dev/null
+++ b/oas_docs/linters/redocly.yaml
@@ -0,0 +1,52 @@
+extends:
+  - recommended
+rules:
+# Built-in rules
+ # Descriptions
+  parameter-description: warn
+  tag-description: warn
+  operation-description: off
+ # Document info
+  info-contact: warn
+  info-license: warn
+ # Examples
+  no-invalid-media-type-examples:
+    severity: warn
+    allowAdditionalProperties: false
+  no-invalid-schema-examples:
+    severity: warn
+    allowAdditionalProperties: false
+ # Operations
+  operation-operationId: error
+  operation-operationId-unique: error
+  operation-operationId-url-safe: warn
+  operation-summary: warn
+ # Parameters
+  path-parameters-defined: warn
+ # Paths
+  no-ambiguous-paths: warn
+  no-identical-paths: error
+  path-excludes-patterns:
+    severity: error
+    patterns:
+      - ^\/internal
+ # Responses
+  operation-4xx-response: off
+  operation-2xx-response: off
+ # Schema
+  spec: off
+  spec-strict-refs: off
+ # Tags
+  operation-tag-defined: off
+  tags-alphabetical: off
+  operation-singular-tag: off
+# Custom rules
+  rule/operation-summary-length:
+    subject:
+      type: Operation
+      property: summary
+    message: Operation summary must have a minimum of 5 and maximum of 45 characters
+    severity: warn
+    assertions:
+      maxLength: 45
+      minLength: 5
\ No newline at end of file
diff --git a/oas_docs/makefile b/oas_docs/makefile
index 2c30b9d874bbb..c97b5046c62a9 100644
--- a/oas_docs/makefile
+++ b/oas_docs/makefile
@@ -22,16 +22,12 @@ api-docs-stateful: ## Generate only kibana.yaml
 	@node scripts/merge_ess_oas.js
 
 .PHONY: api-docs-lint
-api-docs-lint: ## Run spectral API docs linter
-	@npx @stoplight/spectral-cli lint "output/*.yaml" --ruleset ".spectral.yaml"
-
-.PHONY: api-docs-lint-errs
-api-docs-lint-errs: ## Run spectral API docs linter and return only errors
-	@npx @stoplight/spectral-cli lint "output/*.yaml" --ruleset ".spectral.yaml" -D
+api-docs-lint: ## Run redocly API docs linter
+	@npx @redocly/cli lint "output/*.yaml" --config "linters/redocly.yaml" --format stylish --max-problems 500
 
 .PHONY: api-docs-lint-stateful
-api-docs-lint-stateful: ## Run spectral API docs linter on kibana.yaml
-	@npx @stoplight/spectral-cli lint "output/kibana.yaml" --ruleset ".spectral.yaml"
+api-docs-lint-stateful: ## Run redocly API docs linter on kibana.yaml
+	@npx @redocly/cli lint "output/kibana.yaml" --config "linters/redocly.yaml" --format stylish --max-problems 500
 
 .PHONY: api-docs-overlay
 api-docs-overlay: ## Run spectral API docs linter