CLOUDP-283086: POC validator with custom function

Author: lovisaberggren

tools/ipa/Makefile

@@ -0,0 +1,34 @@
+# A Self-Documenting Makefile: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+
+SPECTRAL_VERSION=${SPECTRAL_VERSION:-6.11.1}
+SPECTRAL_CORE_VERSION=${SPECTRAL_CORE_VERSION:-1.19.1}
+
+.PHONY: deps
+deps:  ## Download go module dependencies
+	@echo "==> Installing npx..."
+	npm install -g npx
+
+
+.PHONY: devtools
+devtools:  ## Install dev tools
+	@echo "==> Installing dev tools..."
+	npm install -g @stoplight/spectral-cli@"${SPECTRAL_VERSION}"
+	npm install -g @stoplight/spectral-core@"${SPECTRAL_CORE_VERSION}"
+
+.PHONY: setup
+setup: deps devtools ## Set up dev env
+
+.PHONY: linterr
+linterr: ## Run spectral linter on foas
+	@echo "==> Running spectral linter"
+	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=ruleset.yaml
+
+.PHONY: lintwarn
+lintwarn: ## Run spectral linter on foas
+	@echo "==> Running spectral linter"
+	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=ruleset.yaml --fail-severity=warn
+
+.PHONY: help
+.DEFAULT_GOAL := help
+help:
+	@grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

tools/ipa/functions/hasDescription.js

@@ -0,0 +1,10 @@
+export default (input, _, { path }) => {
+  if (!input.description || input.description === "") {
+    return [
+      {
+        // "property" can be used to print the name of the property we are evaluating
+        message: `#{{print("property")}}MUST have a description.`,
+      },
+    ];
+  }
+}

tools/ipa/ruleset.yaml

@@ -0,0 +1,40 @@
+functions: [hasDescription]
+
+aliases:
+  PathItem:
+    - "$.paths[*]"
+  OperationObject:
+    - "#PathItem[get,put,post,delete,options,head,patch,trace]"
+  DescribableObjects:
+    - "$.info"
+    - "$.tags[*]"
+    - "#OperationObject"
+    - "#PathItem.parameters[?(@ && @.in)]"
+    - "#OperationObject.parameters[?(@ && @.in)]"
+    - "$.components.schemas[*].properties[?(@ && @.type)]"
+
+rules:
+
+  # IPA-117: Documentation
+  xgen-description:
+    description: "API producers must provide descriptions for Properties, Operations and Parameters. http://go/ipa/117"
+    message: "{{error}} http://go/ipa/117"
+    severity: error
+    given: "#DescribableObjects"
+    then:
+        function: "hasDescription" # Doesn't have to be custom, just an example
+
+  xgen-description-format:
+    description: "Descriptions must start with Uppercase and end with a full stop(.). http://go/ipa/117"
+    message: "Description for {{property}} MUST start with Uppercase and end with a full stop(.). http://go/ipa/117"
+    severity: error
+    given: "#DescribableObjects"
+    then:
+      - field: "description"
+        function: pattern
+        functionOptions:
+          match: "/^[A-Z]/"
+      - field: "description"
+        function: pattern
+        functionOptions:
+          match: "\\.|\|$"