Tune OpenAPI linters (#3704)

Author: lcawl

Makefile

@@ -39,7 +39,7 @@ setup:	## Install dependencies for contrib target
 	@make clean-dep
 	@npm install --prefix compiler
 	@npm install --prefix typescript-generator
-	@npm install @stoplight/spectral-cli
+	@npm install @redocly/cli
 
 clean-dep:	## Clean npm dependencies
 	@rm -rf compiler/node_modules
@@ -68,15 +68,15 @@ overlay-docs: ## Apply overlays to OpenAPI documents
 	rm output/openapi/elasticsearch-openapi.tmp*.json
 
 lint-docs: ## Lint the OpenAPI documents after overlays
-	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-*.examples.json --ruleset .spectral.yaml
+	@npx @redocly/cli lint "output/openapi/elasticsearch-*.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
-lint-docs-errs: ## Lint the OpenAPI documents after overlays and return only errors
-	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-*.examples.json --ruleset .spectral.yaml -D
+lint-docs-stateful: ## Lint only the elasticsearch-openapi.examples.json file
+	@npx @redocly/cli lint "output/openapi/elasticsearch-openapi.examples.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
 lint-docs-serverless: ## Lint only the serverless OpenAPI document after overlays
-	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.examples.json --ruleset .spectral.yaml
+	@npx @redocly/cli lint "output/openapi/elasticsearch-serverless-openapi.examples.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
-contrib: | generate license-check spec-format-fix transform-to-openapi filter-for-serverless lint-docs-errs ## Pre contribution target
+contrib: | generate license-check spec-format-fix transform-to-openapi filter-for-serverless lint-docs ## Pre contribution target
 
 help:  ## Display help
 	@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

.spectral.yaml renamed to docs/linters/.spectral.yaml

@@ -0,0 +1,55 @@
+extends:
+  - recommended
+rules:
+# Built-in rules
+ # Descriptions
+  parameter-description: warn
+  tag-description: warn
+  operation-description: off
+ # Document info
+  info-contact: warn
+  info-license: warn
+  no-empty-servers: warn
+ # Examples
+  no-invalid-media-type-examples:
+    severity: off
+    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: off
+  no-identical-paths: warn
+  path-excludes-patterns:
+    severity: error
+    patterns:
+      - ^\/internal
+ # Responses
+  operation-4xx-response: off
+  operation-2xx-response: off
+ # Schema
+  struct: error
+  spec-components-invalid-map-name: off
+  spec-strict-refs: off
+  security-defined: 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

docs/linters/redocly.yaml

@@ -1,4 +1,4 @@
-summary:
+# summary:
 description: >
   A successful response for removing the follower retention leases from the leader index.
 # type: "response"

specification/ccr/forget_follower/examples/response/ForgetFollowerIndexResponseExample1.yaml

@@ -1,4 +1,4 @@
-summary:
+# summary:
 description: A successful response when deleting an existing model snapshot.
 # type: response
 # response_code: 200