Merge branch 'main' into dependabot/npm_and_yarn/compiler/braces-3.0.3

.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> --------------