From a8094606d97fca54cb3abdb54863b746567a1409 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 6 Feb 2025 09:25:41 -0800 Subject: [PATCH] Tune OpenAPI linters (#3704) (cherry picked from commit d1b88afba8ff22e761dd74d4dbccf4382bf3ca25) --- Makefile | 10 ++-- .spectral.yaml => docs/linters/.spectral.yaml | 0 docs/linters/redocly.yaml | 55 +++++++++++++++++++ .../ForgetFollowerIndexResponseExample1.yaml | 2 +- .../ClusterHealthResponseExample1.yaml | 4 +- .../request/PutPipelineRequestExample2.yaml | 2 +- ...MlDeleteModelSnapshotResponseExample1.json | 9 --- ...MlDeleteModelSnapshotResponseExample1.yaml | 6 ++ 8 files changed, 70 insertions(+), 18 deletions(-) rename .spectral.yaml => docs/linters/.spectral.yaml (100%) create mode 100644 docs/linters/redocly.yaml delete mode 100644 specification/ml/delete_model_snapshot/MlDeleteModelSnapshotResponseExample1.json create mode 100644 specification/ml/delete_model_snapshot/examples/response/MlDeleteModelSnapshotResponseExample1.yaml diff --git a/Makefile b/Makefile index a81dd10a16..c161a0289a 100644 --- a/Makefile +++ b/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 @@ -64,12 +64,12 @@ 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 -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\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) diff --git a/.spectral.yaml b/docs/linters/.spectral.yaml similarity index 100% rename from .spectral.yaml rename to docs/linters/.spectral.yaml diff --git a/docs/linters/redocly.yaml b/docs/linters/redocly.yaml new file mode 100644 index 0000000000..e91c2e5694 --- /dev/null +++ b/docs/linters/redocly.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 \ No newline at end of file diff --git a/specification/ccr/forget_follower/examples/response/ForgetFollowerIndexResponseExample1.yaml b/specification/ccr/forget_follower/examples/response/ForgetFollowerIndexResponseExample1.yaml index 32900b9b21..f3f928b8e4 100644 --- a/specification/ccr/forget_follower/examples/response/ForgetFollowerIndexResponseExample1.yaml +++ b/specification/ccr/forget_follower/examples/response/ForgetFollowerIndexResponseExample1.yaml @@ -1,4 +1,4 @@ -summary: +# summary: description: > A successful response for removing the follower retention leases from the leader index. # type: "response" diff --git a/specification/cluster/health/examples/response/ClusterHealthResponseExample1.yaml b/specification/cluster/health/examples/response/ClusterHealthResponseExample1.yaml index 53304058fd..7f7e8bb02c 100644 --- a/specification/cluster/health/examples/response/ClusterHealthResponseExample1.yaml +++ b/specification/cluster/health/examples/response/ClusterHealthResponseExample1.yaml @@ -2,8 +2,8 @@ description: > A successful response from `GET _cluster/health`. It is the health status of a quiet single node cluster with a single index with one shard and one replica. -type: response -response_code: 200 +# type: response +# response_code: 200 value: |- { "cluster_name" : "testcluster", diff --git a/specification/ingest/put_pipeline/examples/request/PutPipelineRequestExample2.yaml b/specification/ingest/put_pipeline/examples/request/PutPipelineRequestExample2.yaml index a36e912842..2b795926aa 100644 --- a/specification/ingest/put_pipeline/examples/request/PutPipelineRequestExample2.yaml +++ b/specification/ingest/put_pipeline/examples/request/PutPipelineRequestExample2.yaml @@ -1,7 +1,7 @@ summary: Create an ingest pipeline with metadata. # method_request: PUT /_ingest/pipeline/my-pipeline-id description: You can use the `_meta` parameter to add arbitrary metadata to a pipeline. -type: request +# type: request value: "{\n \"description\" : \"My optional pipeline description\",\n \"processors\"\ \ : [\n {\n \"set\" : {\n \"description\" : \"My optional processor\ diff --git a/specification/ml/delete_model_snapshot/MlDeleteModelSnapshotResponseExample1.json b/specification/ml/delete_model_snapshot/MlDeleteModelSnapshotResponseExample1.json deleted file mode 100644 index 953cbb8f3e..0000000000 --- a/specification/ml/delete_model_snapshot/MlDeleteModelSnapshotResponseExample1.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "summary": "A successful response when deleting an existing model snapshot.", - "description": "", - "type": "response", - "response_code": 200, - "value": { - "acknowledged": true - } -} diff --git a/specification/ml/delete_model_snapshot/examples/response/MlDeleteModelSnapshotResponseExample1.yaml b/specification/ml/delete_model_snapshot/examples/response/MlDeleteModelSnapshotResponseExample1.yaml new file mode 100644 index 0000000000..0bc54c83f4 --- /dev/null +++ b/specification/ml/delete_model_snapshot/examples/response/MlDeleteModelSnapshotResponseExample1.yaml @@ -0,0 +1,6 @@ +# summary: +description: A successful response when deleting an existing model snapshot. +# type: response +# response_code: 200 +value: + acknowledged: true