feat: new spec build infrastructure (planning#460)

when upstream updates swagger-cli to 4.0.5 this file needs to
be updated to remove the JonasGroeger/swagger-cli project.

.gitlab-ci.yml

@@ -21,8 +21,9 @@ build:
   stage: build
   image: ${CI_REGISTRY}/fit-connect/baseimage:latest
   before_script:
-    - npm install -g @apidevtools/swagger-cli
-    - mkdir dist
+    # See Makefile for as to why this is required
+    - git clone https://github.com/JonasGroeger/swagger-cli.git /tmp/swagger-cli
+    - (cd /tmp/swagger-cli && npm install && npm install -g)
   script:
     - swagger-cli bundle --type yaml --outfile dist/submission-api.yaml spec/submission-api.yaml
   artifacts:
@@ -34,7 +35,7 @@ build:
 lint:
   stage: lint
   image:
-    name: $CI_REGISTRY/stoplight/spectral:5
+    name: ${CI_REGISTRY}/stoplight/spectral:6
     entrypoint: [ "" ]
   script:
     - spectral lint spec/submission-api.yaml --verbose --display-only-failures

.spectral.yml

@@ -3,32 +3,30 @@ extends:
   - https://italia.github.io/api-oas-checker/spectral-generic.yml
   - https://italia.github.io/api-oas-checker/spectral-security.yml
 
-functionsDir: './functions'
-functions:
-  - pagination-response
-
 rules:
-  no-default-additionalProperties: off
-  string-maxlength: hint
-  typed-enum: error
-  response-with-json-object: error
+  # Broken rules (spectral crashes) in spectral-generic.yml
+  cache-responses-undocumented: off
+  cache-control-parameter-undocumented: off
+  servers-use-https: off
+  no-method-name-in-operationId: off
 
-  # Disabled, since we don't want a /status endpoint.
-  # See https://git.fitko.de/fit-connect/api/-/merge_requests/37
-  paths-status: off
-  paths-status-return-problem: off
-  paths-status-problem-schema: off
+  # Broken rules (spectral crashes) in spectral-security.yml
+  sec-array-boundaries: off
+  sec-number-boundaries: off
+  sec-no-additionalProperties: off
+  sec-no-default-additionalProperties: off
+  sec-constrained-additionalProperties: off
+  sec-securitySchemes-oauth: off
+  sec-securitySchemes-jwt: off
+  sec-string-maxlength: off
+  sec-string-pattern-or-format-or-enum: off
 
-  use-semver: off # Versioning is handled by CI
-  patch-media-type: off
+  # API_VERSION is only set during release
+  use-semver: warn
 
-  cache-responses-undocumented: off
+  # Disabled, since we don't want a /status endpoint.
+  # See https://git.fitko.de/fit-connect/api/-/merge_requests/37
+  paths-status: warn
 
-  check-for-pagination:
-    description: An operation that returns a list and less than 4 properties could perhaps support pagination.
-    message: '{{error}}'
-    severity: warn
-    given:
-      - $.paths.*[get]
-    then:
-      function: pagination-response
+  # Our PATCH endpoints are not PATCH compliant
+  patch-media-type: warn

Makefile

+.DEFAULT_GOAL := validate-build
+.PHONY: install print-version bundle validate validate-build bundle-dereferenced spectral
+
+# The standard @apidevtools/swagger-cli does NOT install @apidevtools/swagger-parser > 10.1.0 which
+# is required for OpenAPI version 3.1.0. But there is a branch from JonasGroeger that fixes that.
+# Once upstream updates their dependencies (see https://github.com/APIDevTools/swagger-cli/pull/78)
+# we can remove this install target and use
+#     npm install -g @apidevtools/swagger-cli
+# again.
+install:
+	git clone https://github.com/JonasGroeger/swagger-cli.git /tmp/swagger-cli
+	cd /tmp/swagger-cli && npm install && sudo npm install -g
+	chmod +x /tmp/swagger-cli/bin/swagger-cli.js
+	/tmp/swagger-cli/bin/swagger-cli.js --version
+
+print-version:
+	swagger-cli --version
+
+bundle: print-version
+	swagger-cli bundle \
+		--type yaml \
+		--outfile dist/submission-api.yaml \
+		spec/submission-api.yaml
+
+validate: print-version
+	swagger-cli validate spec/submission-api.yaml
+
+validate-build: bundle
+	swagger-cli validate dist/submission-api.yaml
+
+bundle-dereferenced: print-version
+	swagger-cli bundle \
+		--type yaml \
+		--outfile dist/submission-api.yaml \
+		--dereference \
+		spec/submission-api.yaml
+
+pwd := $(shell pwd)
+
+spectral: bundle
+	docker run --rm --pull=always \
+		-v "$(pwd):/work" -w /work \
+		stoplight/spectral:6 lint spec/submission-api.yaml -D