enhance(spec): automate worker api spec generation

.github/workflows/spec.yml

@@ -0,0 +1,33 @@
+# name of the action
+name: spec
+
+# trigger on release events
+on:
+  release:
+    types: [ created ]
+
+# pipeline to execute
+jobs:
+  schema:
+    runs-on: ubuntu-latest
+    container:
+      image: golang:1.17
+    steps:
+    - name: clone
+      uses: actions/checkout@v2
+
+    - name: tags
+      run: |
+        git fetch --tags
+
+    - name: create spec
+      run: |
+        make spec-install
+        make spec
+
+    - name: upload spec
+      uses: skx/github-action-publish-binaries@master
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        args: 'api-spec.json'

.github/workflows/validate.yml

@@ -26,3 +26,8 @@ jobs:
         go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)
         # Check that go fix ./... produces a zero diff; clean up any changes afterwards.
         go fix ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)
+
+    - name: validate spec
+      run: |
+        make spec-install
+        make spec

.gitignore

@@ -42,3 +42,5 @@ secrets.env
 
 # Files to be excluded.
 .DS_Store
+
+api-spec.json

Makefile

@@ -5,6 +5,9 @@
 # capture the current date we build the application from
 BUILD_DATE = $(shell date +%Y-%m-%dT%H:%M:%SZ)
 
+# set the filename for the api spec
+SPEC_FILE = api-spec.json
+
 # check if a git commit sha is already set
 ifndef GITHUB_SHA
 	# capture the current git commit sha we build the application from
@@ -243,3 +246,68 @@ compose-down:
 	@echo
 	@echo "### Destroying containers for docker-compose stack"
 	@docker-compose -f docker-compose.yml down
+
+# The `spec-install` target is intended to install the
+# the needed dependencies to generate the api spec.
+# 
+# Tools used:
+# - go-swagger (https://goswagger.io/install.html)
+# - jq (https://stedolan.github.io/jq/download/)
+# - sponge (part of moreutils - https://packages.debian.org/sid/moreutils)
+#
+# Limit use of this make target to CI.
+# Debian-based environment is assumed.
+#
+# Usage: `make spec-install`
+.PHONY: spec-install
+spec-install:
+	$(if $(shell command -v apt-get 2> /dev/null),,$(error 'apt-get' not found - install jq, sponge, and go-swagger manually))
+	@echo
+	@echo "### Installing utilities (jq and sponge)"
+	@apt-get update
+	@apt-get install -y jq moreutils
+	@echo "### Downloading and installing go-swagger"
+	@curl -o /usr/local/bin/swagger -L "https://github.com/go-swagger/go-swagger/releases/download/v0.27.0/swagger_linux_amd64"
+	@chmod +x /usr/local/bin/swagger
+
+# The `spec-gen` target is intended to create an api-spec
+# using go-swagger (https://goswagger.io)
+#
+# Usage: `make spec-gen`
+.PHONY: spec-gen
+spec-gen:
+	@echo
+	@echo "### Generating api spec using go-swagger"
+	@swagger generate spec -m --exclude github.com/docker/docker/api/types --exclude-tag definitions/Step -o ${SPEC_FILE}
+	@echo "### ${SPEC_FILE} created successfully"
+
+# The `spec-validate` target is intended to validate
+# an api-spec using go-swagger (https://goswagger.io)
+#
+# Usage: `make spec-validate`
+.PHONY: spec-validate
+spec-validate:
+	@echo
+	@echo "### Validating api spec using go-swagger"
+	@swagger validate ${SPEC_FILE}
+
+# The `spec-version-update` target is intended to update
+# the api-spec version in the generated api-spec
+# using the latest git tag.
+#
+# Usage: `make spec-version-update`
+.PHONY: spec-version-update
+spec-version-update: APPS = jq sponge
+spec-version-update:
+	$(foreach app,$(APPS),\
+		$(if $(shell command -v $(app) 2> /dev/null),,$(error skipping update of spec version - '$(app)' not found)))
+	@echo
+	@echo "### Updating api-spec version"
+	@jq '.info.version = "$(subst v,,${GITHUB_TAG})"' ${SPEC_FILE} | sponge ${SPEC_FILE}
+
+# The `spec` target will call spec-gen, spec-version-update
+# and spec-validate to create and validate an api-spec.
+#
+# Usage: `make spec`
+.PHONY: spec
+spec: spec-gen spec-version-update spec-validate