Add Spectral Linter

.gitignore

@@ -1,4 +1,5 @@
 /vendor
+/node_modules
 
 /docker-compose.override.yml
 

.gitlab-ci.dist.yml

@@ -0,0 +1,71 @@
+# .gitlab-ci.yml example
+# rename this file and adjust to your needs to enable Gitlab CI
+stages:
+  - lint
+  - test
+
+# cache composer vendor
+cache:
+  paths:
+    - vendor/
+
+# run linter against the openapi specification
+lint-api-spec:
+  stage: lint
+  interruptible: true
+  before_script:
+    - make start-docker
+    - make node_modules/.bin/spectral
+  script:
+    - make lint
+  after_script:
+    - make stop-docker
+
+# run generator and make sure no changes are uncommitted
+check-generator-changes:
+  stage: lint
+  interruptible: true
+  before_script:
+    - make start-docker
+    - echo "Waiting for mariadb to start up..."
+    - docker-compose exec -T backend-php timeout 60s sh -c "while ! (mysql -uapi_test -papisecret -h db-test --execute 'SELECT 1;' > /dev/null 2>&1); do echo -n '.'; sleep 0.1 ; done; echo 'ok'" || (docker-compose ps; docker-compose logs; exit 1)
+    - make run COMMAND="./yii migrate/up --interactive=0"
+  script:
+    - make run COMMAND="./yii gii/api --interactive=0 --overwrite"
+    - git diff --exit-code
+    - git status -s && test -z "$(git status -s)"
+  after_script:
+    - make stop-docker
+
+# run tests
+tests:
+  stage: test
+  before_script:
+    - make start-docker
+    - echo "Waiting for mariadb to start up..."
+    - docker-compose exec -T backend-php timeout 60s sh -c "while ! (mysql -uapi_test -papisecret -h db-test --execute 'SELECT 1;' > /dev/null 2>&1); do echo -n '.'; sleep 0.1 ; done; echo 'ok'" || (docker-compose ps; docker-compose logs; exit 1)
+  script:
+    - make test
+  after_script:
+    - make stop-docker
+    - sudo rm -rf docker/_data/*
+  artifacts:
+    paths:
+      - tests/_output
+    exclude:
+      - tests/_output/.gitignore
+    when: always
+    expire_in: 2 week
+    reports:
+      # make the report available in Gitlab UI. see https://docs.gitlab.com/ee/ci/unit_test_reports.html
+      junit:
+        - tests/_output/*.xml
+
+variables:
+  GIT_STRATEGY: fetch
+  GIT_SUBMODULE_STRATEGY: recursive
+  # solve docker timeout issues
+  # https://github.com/docker/compose/issues/4486
+  DOCKER_CLIENT_TIMEOUT: 300
+  COMPOSE_HTTP_TIMEOUT: 300
+

.spectral.yml

@@ -0,0 +1,8 @@
+# This file configures the spectral OpenAPI linter
+#
+# The default config extends the pre-defined ruleset for OpenAPI 3.
+# Adjust this file to define your own custom rules.
+#
+# See https://meta.stoplight.io/docs/spectral/01baf06bdd05a-create-a-ruleset
+
+extends: ["spectral:oas"]

Makefile

@@ -1,7 +1,7 @@
 # set user to "root" to run commands as root in docker
 USER=$$(whoami)
 # The docker command to execute commands directly in docker
-DOCKER=docker-compose exec -T --user="$(USER)" backend-php
+DOCKER=docker-compose exec -T -w /app --user="$(USER)" backend-php
 # The PHP binary to use, you may add arguments to PHP here
 PHP=php
 # directories writeable by webserver
@@ -20,9 +20,10 @@ default:
 	@echo "  make stop-docker    stop docker environment"
 	@echo "  make cli            run bash in docker environment"
 	@echo "  make bash           alias for 'make cli'"
+	@echo "  make lint           Run OpenAPI linter"
 
 
-.PHONY: start stop start-docker stop-docker clean test bash cli
+.PHONY: start stop start-docker stop-docker clean test bash cli lint lint-php lint-js
 
 
 ## PHP runtime ##
@@ -81,6 +82,19 @@ backend/config/cookie-validation.key:
 	test -s $@ || php -r 'echo bin2hex(random_bytes(20));' > $@
 
 
+# Lint API spec
+
+lint: lint-php lint-js
+
+lint-php:
+	$(DOCKER) ./vendor/bin/php-openapi validate openapi/schema.yaml
+
+lint-js: node_modules/.bin/spectral
+	docker-compose run -T --no-deps --rm --user="$$(id -u)" -e FORCE_COLOR=1 -w /app nodejs ./node_modules/.bin/spectral lint openapi/schema.yaml -f stylish --ruleset .spectral.yml
+
+node_modules/.bin/spectral: package.json
+	docker-compose run -T --no-deps --rm --user="$$(id -u)" -e FORCE_COLOR=1 -w /app nodejs npm install
+
 ## Docker Runtime Tests ##
 
 test: tests/_data/dump.sql

README.md

@@ -150,6 +150,18 @@ Your API is now available at `http://localhost:8337/`. Try to access an endpoint
         ...
     ]
 
+
+## Linting the OpenAPI specification
+
+You can run a linter to check the validity of your OpenAPI specification file:
+
+    make lint-js  # run spectral lint
+    make lint-php # run php-openapi validate
+    make lint     # run both of the above commands
+
+You can find more information on spectral at <https://www.npmjs.com/package/@stoplight/spectral-cli#-documentation-and-community>.
+
+
 ## Application structure <span id="structure"></span>
 
 This application template consists of 3 application tiers:

docker-compose.yml

@@ -52,3 +52,9 @@ services:
   mailcatcher:
     image: nisenabe/mailcatcher
 
+  # javascript container for running JS OpenAPI linter
+  nodejs:
+    image: node
+    command: 'tail -f /dev/null'
+    volumes:
+      - ./:/app