From de95bb34a267819c4f515c7bfc16537a5a5fd89b Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 17 Jun 2024 15:09:23 -0700 Subject: [PATCH 1/5] Add spectral linting rules --- .spectral.yaml | 103 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 .spectral.yaml diff --git a/.spectral.yaml b/.spectral.yaml new file mode 100644 index 0000000000..b328e320e2 --- /dev/null +++ b/.spectral.yaml @@ -0,0 +1,103 @@ +extends: ["spectral:oas"] +rules: +# Built-in rules + # Descriptions + oas3-parameter-description: warn + oas2-parameter-description: warn + tag-description: info + # Document info + info-contact: info + info-description: warn + info-license: warn + # Examples + oas3-valid-media-example: false + oas3-valid-schema-example: false + oas2-valid-media-example: false + # Operations + operation-operationId: false + operation-operationId-unique: false + operation-operationId-valid-in-url: false + operation-tag-defined: warn + operation-tags: warn + # Responses + operation-success-response: warn + # Schema + oas3-schema: error + oas2-schema: error + # Tags + openapi-tags: warn + openapi-tags-alphabetical: info + # Turn off some built-in rules + operation-description: false + operation-singular-tag: false +# Custom rules + # Descriptions + avoid-problematic-words: + description: Ban certain words from descriptions + message: "Use appropriate replacements for problematic terms" + severity: warn + given: "$..*.description" + then: + function: pattern + functionOptions: + notMatch: /(blacklist|whitelist|execute|kill)/i + # Examples + operation-success-examples: + formats: ["oas3_1"] + description: Response code 200 should have at least one example. + message: "Each response body should have a realistic example. It must not contain any sensitive or confidential data." + severity: info + given: $.paths[*].[*].responses.[200].content.[application/json] + then: + field: examples + function: defined + # Extensions + internal-extension: + description: Operations should not have x-internal extension. + message: "Do not publish x-internal operations" + severity: error + given: $.paths[*].[get,put,post,delete,options,head,patch,trace] + then: + field: x-internal + function: undefined + # Operations + operation-summary: + description: Operations should have summaries. + message: "Each operation should have a summary" + severity: error + recommended: true + given: $.paths[*].[get,put,post,delete,options,head,patch,trace] + then: + field: summary + function: defined + operation-summary-length: + description: Operation summary should be between 5 and 45 characters + given: "$.paths[*].[get,put,post,delete,options,head,patch,trace]" + then: + field: summary + function: length + functionOptions: + max: 45 + min: 5 + severity: warn + simple-verbs-in-summary: + given: + - "$.paths[*][*].summary" + then: + function: pattern + functionOptions: + notMatch: "Retrieve|Return|List *" + severity: warn + description: Summaries should use common verbs. + message: "Summaries should use common verbs like Get, Update, Delete whenever possible" + # NOTE: This one hiccups on acronyms so perhaps too noisy + # docs-operation-summary-sentence-case: + # description: Operation summary should be sentence cased + # given: "$.paths[*].[get,put,post,delete,options,head,patch,trace]" + # then: + # field: summary + # function: pattern + # functionOptions: + # match: /^[A-Z]+[^A-Z]+$/ + # severity: warn + From f1c669f0e7a5eaa13430db1ac42d5691ff816007 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 17 Jun 2024 15:26:20 -0700 Subject: [PATCH 2/5] Add Spectral linting rules --- .spectral.yaml | 2 +- Makefile | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.spectral.yaml b/.spectral.yaml index b328e320e2..82886069f5 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -69,7 +69,7 @@ rules: given: $.paths[*].[get,put,post,delete,options,head,patch,trace] then: field: summary - function: defined + function: defined operation-summary-length: description: Operation summary should be between 5 and 45 characters given: "$.paths[*].[get,put,post,delete,options,head,patch,trace]" diff --git a/Makefile b/Makefile index 44ce12bce1..03b736e89f 100644 --- a/Makefile +++ b/Makefile @@ -39,6 +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 clean-dep: ## Clean npm dependencies @rm -rf compiler/node_modules @@ -58,6 +59,9 @@ dump-routes: ## Create a new schema with all generics expanded contrib: | generate license-check spec-format-fix transform-to-openapi ## Pre contribution target +lint-docs: ## Lint the OpenAPI documents + @npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json + 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) #------------- -------------- From 3c59a06cc145dedfcd761f9e7eec2fe69f64d0bc Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 17 Jun 2024 15:42:15 -0700 Subject: [PATCH 3/5] Fix async search status operation summary --- .spectral.yaml | 2 +- output/schema/schema.json | 4 ++-- specification/async_search/status/AsyncSearchStatusRequest.ts | 1 + 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.spectral.yaml b/.spectral.yaml index 82886069f5..63ef81a950 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -66,7 +66,7 @@ rules: message: "Each operation should have a summary" severity: error recommended: true - given: $.paths[*].[get,put,post,delete,options,head,patch,trace] + given: $.paths[*][*] then: field: summary function: defined diff --git a/output/schema/schema.json b/output/schema/schema.json index ea00453bb3..fe4997d47c 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -83056,7 +83056,7 @@ "body": { "kind": "no_body" }, - "description": "Retreives the status of a previously submitted async search request given its identifier, without retrieving search results.\nIf the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.", + "description": "Get async search status\nRetreives the status of a previously submitted async search request given its identifier, without retrieving search results.\nIf the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.", "inherits": { "type": { "name": "RequestBase", @@ -83083,7 +83083,7 @@ } ], "query": [], - "specLocation": "async_search/status/AsyncSearchStatusRequest.ts#L23-L36" + "specLocation": "async_search/status/AsyncSearchStatusRequest.ts#L23-L37" }, { "body": { diff --git a/specification/async_search/status/AsyncSearchStatusRequest.ts b/specification/async_search/status/AsyncSearchStatusRequest.ts index 7652da42f0..838376765b 100644 --- a/specification/async_search/status/AsyncSearchStatusRequest.ts +++ b/specification/async_search/status/AsyncSearchStatusRequest.ts @@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** + * Get async search status * Retreives the status of a previously submitted async search request given its identifier, without retrieving search results. * If the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role. * @rest_spec_name async_search.status From 3834a601a0d638d6388701c97d9b244d682a1141 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 17 Jun 2024 15:44:41 -0700 Subject: [PATCH 4/5] Fixes typo --- output/schema/schema.json | 2 +- specification/async_search/status/AsyncSearchStatusRequest.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index fe4997d47c..47dd5949a2 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -83056,7 +83056,7 @@ "body": { "kind": "no_body" }, - "description": "Get async search status\nRetreives the status of a previously submitted async search request given its identifier, without retrieving search results.\nIf the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.", + "description": "Get async search status\nRetrieves the status of a previously submitted async search request given its identifier, without retrieving search results.\nIf the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.", "inherits": { "type": { "name": "RequestBase", diff --git a/specification/async_search/status/AsyncSearchStatusRequest.ts b/specification/async_search/status/AsyncSearchStatusRequest.ts index 838376765b..cf416214d6 100644 --- a/specification/async_search/status/AsyncSearchStatusRequest.ts +++ b/specification/async_search/status/AsyncSearchStatusRequest.ts @@ -22,7 +22,7 @@ import { Id } from '@_types/common' /** * Get async search status - * Retreives the status of a previously submitted async search request given its identifier, without retrieving search results. + * Retrieves the status of a previously submitted async search request given its identifier, without retrieving search results. * If the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role. * @rest_spec_name async_search.status * @availability stack since=7.11.0 stability=stable From cf55866f38b2b5f765114e34dac5b25007a9c84c Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 17 Jun 2024 16:01:37 -0700 Subject: [PATCH 5/5] Edit MlCloseJobRequest.ts summary --- .spectral.yaml | 4 ++-- output/schema/schema.json | 2 +- specification/ml/close_job/MlCloseJobRequest.ts | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.spectral.yaml b/.spectral.yaml index 63ef81a950..6763814cd1 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -22,8 +22,8 @@ rules: # Responses operation-success-response: warn # Schema - oas3-schema: error - oas2-schema: error + oas3-schema: warn + oas2-schema: warn # Tags openapi-tags: warn openapi-tags-alphabetical: info diff --git a/output/schema/schema.json b/output/schema/schema.json index 47dd5949a2..546bcb181b 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -153680,7 +153680,7 @@ } ] }, - "description": "Closes one or more anomaly detection jobs.\nA job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.\nWhen you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.\nIf you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.\nWhen a datafeed that has a specified end date stops, it automatically closes its associated job.", + "description": "Close anomaly detection jobs\nA job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.\nWhen you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.\nIf you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.\nWhen a datafeed that has a specified end date stops, it automatically closes its associated job.", "inherits": { "type": { "name": "RequestBase", diff --git a/specification/ml/close_job/MlCloseJobRequest.ts b/specification/ml/close_job/MlCloseJobRequest.ts index 29b95be39f..da30f6e2b7 100644 --- a/specification/ml/close_job/MlCloseJobRequest.ts +++ b/specification/ml/close_job/MlCloseJobRequest.ts @@ -22,7 +22,7 @@ import { Id } from '@_types/common' import { Duration } from '@_types/Time' /** - * Closes one or more anomaly detection jobs. + * Close anomaly detection jobs * A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. * When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. * If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.