refactor(spec): port the OpenAPI spec to TypeSpec

api/openapi-spec/v1.0.yaml becomes a build artefact compiled from
spec/*.tsp; every client pipeline runs the compile step before
generating, and a Makefile + scripts cover local generation. Sibling
endpoints share templated operations (DriveItemOps, PermissionsOps,
LibreGraphOps) so identical routes cannot drift apart. Pins TypeSpec
1.13.0.

Semantic changes against the previous YAML:
- add GET /v1.0/drives/{drive-id}/root/children and
  GET /v1.0/drives/{drive-id}/items/{item-id}/children
- CreateInvitation's request body is now required
- invitation ops gained the missing 'default: odata.error' response
- example blocks fixed to match their schemas (grantedToV2 as single
  object, parentReference.driveId casing, @UI.Hidden,
  onPremisesSamAccountName, {value: [...]} collection wrappers)

Generated Go and TypeScript clients are structurally unchanged.

Author: dschmidt

.gitignore

@@ -1,3 +1,11 @@
 composer.lock
 vendor
-tmp
+tmp
+
+# Generated by `make spec` (`scripts/compile-spec.sh`).
+api/openapi-spec/v1.0.yaml
+
+# Local build artefacts.
+build/
+spec/build/
+spec/node_modules/

.woodpecker/build-cpp-qt.yaml

@@ -1,6 +1,7 @@
 ---
 variables:
   - &alpine_image 'owncloudci/alpine:latest'
+  - &node_image 'node:22-alpine'
   - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5'
   - &environment
     HTTP_PROXY:
@@ -21,20 +22,17 @@ steps:
       ref: HEAD
       path: libre-graph-api-cpp-qt-client
       remote: https://github.com/opencloud-eu/libre-graph-api-cpp-qt-client.git
+  compile-spec:
+    image: *node_image
+    environment: *environment
+    commands:
+      - sh scripts/compile-spec.sh
   generate-cpp-qt:
     image: *generator_image
     environment: *environment
     commands:
       - rm -Rf libre-graph-api-cpp-qt-client/*
-      - '/usr/local/bin/docker-entrypoint.sh generate
-        --enable-post-process-file
-        -i api/openapi-spec/v1.0.yaml
-        --additional-properties=packageName=libregraph
-        --git-user-id=opencloud-eu
-        --git-repo-id=libre-graph-api-cpp-qt-client
-        -g cpp-qt-client
-        -t templates/cpp-qt-client
-        -o libre-graph-api-cpp-qt-client'
+      - sh scripts/generate-cpp-qt-client.sh
       - cp LICENSE libre-graph-api-cpp-qt-client/LICENSE
   diff:
     image: *alpine_image

.woodpecker/build-go.yaml

@@ -1,6 +1,7 @@
 ---
 variables:
   - &alpine_image 'owncloudci/alpine:latest'
+  - &node_image 'node:22-alpine'
   - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5'
   - &environment
     HTTP_PROXY:
@@ -21,20 +22,17 @@ steps:
       ref: HEAD
       path: libre-graph-api-go
       remote: https://github.com/opencloud-eu/libre-graph-api-go.git
+  compile-spec:
+    image: *node_image
+    environment: *environment
+    commands:
+      - sh scripts/compile-spec.sh
   generate-go:
     image: *generator_image
     environment: *environment
     commands:
       - rm -Rf libre-graph-api-go/*
-      - '/usr/local/bin/docker-entrypoint.sh generate
-        --enable-post-process-file
-        -i api/openapi-spec/v1.0.yaml
-        --additional-properties=packageName=libregraph
-        --git-user-id=opencloud-eu
-        --git-repo-id=libre-graph-api-go
-        -g go
-        -o libre-graph-api-go
-        --api-name-suffix Api'
+      - sh scripts/generate-go.sh
       - cp LICENSE libre-graph-api-go/LICENSE
   diff:
     image: *alpine_image

.woodpecker/build-php.yaml

@@ -1,6 +1,7 @@
 ---
 variables:
   - &alpine_image 'owncloudci/alpine:latest'
+  - &node_image 'node:22-alpine'
   - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5'
   - &environment
     HTTP_PROXY:
@@ -21,20 +22,17 @@ steps:
       ref: HEAD
       path: libre-graph-api-php
       remote: https://github.com/opencloud-eu/libre-graph-api-php.git
+  compile-spec:
+    image: *node_image
+    environment: *environment
+    commands:
+      - sh scripts/compile-spec.sh
   generate-php:
     image: *generator_image
     environment: *environment
     commands:
       - rm -Rf libre-graph-api-php/*
-      - '/usr/local/bin/docker-entrypoint.sh generate
-        --enable-post-process-file
-        -i api/openapi-spec/v1.0.yaml
-        --additional-properties=packageName=libregraph
-        --git-user-id=opencloud-eu
-        --git-repo-id=libre-graph-api-php
-        -g php-nextgen
-        -t templates/php-nextgen
-        -o libre-graph-api-php'
+      - sh scripts/generate-php.sh
       - cp LICENSE libre-graph-api-php/LICENSE
   diff:
     image: *alpine_image

.woodpecker/build-typescript-axios.yaml

@@ -1,6 +1,7 @@
 ---
 variables:
   - &alpine_image 'owncloudci/alpine:latest'
+  - &node_image 'node:22-alpine'
   - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5'
   - &environment
     HTTP_PROXY:
@@ -21,20 +22,17 @@ steps:
       ref: HEAD
       path: libre-graph-api-typescript-axios
       remote: https://github.com/opencloud-eu/libre-graph-api-typescript-axios.git
+  compile-spec:
+    image: *node_image
+    environment: *environment
+    commands:
+      - sh scripts/compile-spec.sh
   generate-typescript-axios:
     image: *generator_image
     environment: *environment
     commands:
       - rm -Rf libre-graph-api-typescript-axios/*
-      - '/usr/local/bin/docker-entrypoint.sh generate
-        --enable-post-process-file
-        -i api/openapi-spec/v1.0.yaml
-        --additional-properties=packageName=libregraph
-        --git-user-id=opencloud-eu
-        --git-repo-id=libre-graph-api-typescript-axios
-        -g typescript-axios
-        -o libre-graph-api-typescript-axios
-        --api-name-suffix Api'
+      - sh scripts/generate-typescript-axios.sh
       - cp LICENSE libre-graph-api-typescript-axios/LICENSE
   diff:
     image: *alpine_image

.woodpecker/docs.yaml

@@ -1,10 +1,17 @@
 ---
+variables:
+  - &node_image 'node:22-alpine'
+
 when:
   - event: push
     branch: ${CI_REPO_DEFAULT_BRANCH}
   - event: [ manual, tag]
 
 steps:
+  - name: compile-spec
+    image: *node_image
+    commands:
+      - sh scripts/compile-spec.sh
   - name: deploy-staging
     image: debian:latest
     environment:
@@ -22,7 +29,7 @@ steps:
       - ssh-keyscan -t rsa $REMOTE_HOST >> $HOME/.ssh/known_hosts
       - echo "$SSH_KEY" > "$HOME/.ssh/id_rsa"
       - chmod 0600 $HOME/.ssh/id_rsa
-      - rsync -a --exclude '.git' --delete . $REMOTE_HOST:/var/swagger/libre-graph-api
+      - rsync -a --exclude '.git' --exclude 'spec/node_modules' --exclude 'spec/build' --exclude 'build' --delete . $REMOTE_HOST:/var/swagger/libre-graph-api
   - name: deploy-production
     image: debian:latest
     environment:
@@ -39,4 +46,4 @@ steps:
       - ssh-keyscan -t rsa $REMOTE_HOST >> $HOME/.ssh/known_hosts
       - echo "$SSH_KEY" > "$HOME/.ssh/id_rsa"
       - chmod 0600 $HOME/.ssh/id_rsa
-      - rsync -a --exclude '.git' --delete . woodpeckersyncer@$REMOTE_HOST:/var/swagger/libre-graph-api
+      - rsync -a --exclude '.git' --exclude 'spec/node_modules' --exclude 'spec/build' --exclude 'build' --delete . woodpeckersyncer@$REMOTE_HOST:/var/swagger/libre-graph-api

Makefile

@@ -0,0 +1,51 @@
+# libre-graph-api local build entry points.
+#
+# `make` (or `make spec`) compiles the TypeSpec sources under spec/ into
+# api/openapi-spec/v1.0.yaml. Per-language client generation targets pull the
+# matching openapi-generator-cli image straight out of the woodpecker pipeline
+# file for that language, so renovatebot remains the single source of truth
+# for the generator version.
+
+SPEC         := api/openapi-spec/v1.0.yaml
+SPEC_SOURCES := $(wildcard spec/*.tsp) spec/tspconfig.yaml spec/package.json spec/package-lock.json
+NODE_IMAGE   := node:22-alpine
+
+# Extract `openapitools/openapi-generator-cli:<tag>@sha256:<digest>` from the
+# .woodpecker pipeline file for the given language.
+#   $(call generator_image,go)
+#   $(call generator_image,typescript-axios)
+generator_image = $(shell grep -oE "openapitools/openapi-generator-cli:[A-Za-z0-9._@:-]+" .woodpecker/build-$(1).yaml | head -n1)
+
+DOCKER_RUN = docker run --rm \
+	--user $(shell id -u):$(shell id -g) \
+	-v "$(CURDIR):/work" \
+	-w /work
+
+.PHONY: all spec go typescript-axios php cpp-qt-client clean help
+
+all: spec
+
+help: ## Show this help
+	@echo "Common commands:"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+spec: $(SPEC) ## Compile TypeSpec sources into api/openapi-spec/v1.0.yaml
+
+$(SPEC): $(SPEC_SOURCES)
+	$(DOCKER_RUN) -e HOME=/tmp -e npm_config_cache=/tmp/.npm $(NODE_IMAGE) sh scripts/compile-spec.sh
+
+go: $(SPEC) ## Generate the Go client into build/clients/go
+	$(DOCKER_RUN) -e OUTPUT_DIR=build/clients/go $(call generator_image,go) sh scripts/generate-go.sh
+
+typescript-axios: $(SPEC) ## Generate the TypeScript-Axios client into build/clients/typescript-axios
+	$(DOCKER_RUN) -e OUTPUT_DIR=build/clients/typescript-axios $(call generator_image,typescript-axios) sh scripts/generate-typescript-axios.sh
+
+php: $(SPEC) ## Generate the PHP client into build/clients/php
+	$(DOCKER_RUN) -e OUTPUT_DIR=build/clients/php $(call generator_image,php) sh scripts/generate-php.sh
+
+cpp-qt-client: $(SPEC) ## Generate the C++/Qt client into build/clients/cpp-qt-client
+	$(DOCKER_RUN) -e OUTPUT_DIR=build/clients/cpp-qt-client $(call generator_image,cpp-qt) sh scripts/generate-cpp-qt-client.sh
+
+clean: ## Remove build artefacts and the generated spec
+	rm -rf build/ spec/build/ $(SPEC)