Add Spectral Linter

Author: cebe

.gitignore

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

.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