Add Spectral linting rules for openAPI documents (#2618)

.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: warn
+  oas2-schema: warn
+  # 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[*][*]
+    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
+

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<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)
 #------------- <https://suva.sh/posts/well-documented-makefiles> --------------

specification/async_search/status/AsyncSearchStatusRequest.ts

@@ -21,7 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Retreives the status of a previously submitted async search request given its identifier, without retrieving search results.
+ * Get async search status
+ * 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

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.