spiceai · zdunecki · Jan 25, 2026
diff --git a/openapi/Makefile b/openapi/Makefile
@@ -0,0 +1,2 @@
+client:
+	./client.sh
diff --git a/openapi/README.md b/openapi/README.md
@@ -0,0 +1,28 @@
+# Spice.ai Go OpenAPI
+
+Go OpenAPI client generated from the Spice.ai OpenAPI spec.
+
+## Usage
+
+Generate the client using the version specified in `doc.go`:
+
+```bash
+make client
+```
+
+Or override the version with an environment variable:
+
+```bash
+VERSION=trunk make client
+VERSION=v1.11.0-rc.3 make client
+```
+
+The script will:
+1. Download `openapi.json` from GitHub (tries tags first, then branches)
+2. Generate Go client code using `openapi-generator-cli`
+3. Clean up temporary files
+
+## Requirements
+
+- Docker (for running `openapi-generator-cli`)
+- curl
diff --git a/openapi/TODO.md b/openapi/TODO.md
@@ -0,0 +1,48 @@
+# TODO
+
+## 1. SpecValidationException 
+
+> (workaround: `--skip-validate-spec`)
+
+```sh
+Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
+ | Error count: 3, Warning count: 2
+Errors: 
+        -attribute paths.'/v1/tools'(get).operationId is repeated
+        -paths.'/v1/iceberg/namespaces/{namespace}'. Declared path parameter namespace needs to be defined as a path parameter in path or operation level
+        -attribute paths.'/v1/mcp/sse'(post).parameters.[sessionId].content is missing
+Warnings: 
+        -attribute paths.'/v1/tools'(get).operationId is repeated
+        -paths.'/v1/iceberg/namespaces/{namespace}'. Declared path parameter namespace needs to be defined as a path parameter in path or operation level
+        -attribute paths.'/v1/mcp/sse'(post).parameters.[sessionId].content is missing
+
+        at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:718)
+        at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:745)
+        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:527)
+        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
+        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
+```
+
+## 2. OpenAPI 3.1 Support
+
+Tried multiple Go client generators but none supported OpenAPI 3.1 well:
+- **ogen** - lacks full 3.1 support
+- **oapi-codegen** - lacks full 3.1 support
+- **openapi-generator-cli** - works with `--skip-validate-spec`
+
+Using `openapi-generator-cli` (Java-based) via Docker as the most compatible option.
+
+### 2.1. Evaluate Alternative Client Generators
+
+Consider trying other generators that may have better OpenAPI 3.1 support:
+- **Fern** - https://github.com/fern-api/fern
+- **Speakeasy** - https://github.com/speakeasy-api/speakeasy
+- **go-swagger** - https://github.com/go-swagger/go-swagger
+
+## 3. Generate HTTP Client
+
+Currently only generating models (`--global-property=models`). Need to also generate a full HTTP client with:
+- API methods for each endpoint
+- Request/response handling
+- Authentication support
+- Error handling
diff --git a/openapi/client.sh b/openapi/client.sh
@@ -0,0 +1,104 @@
+#!/bin/bash
+
+# Generate Go client from OpenAPI spec using Docker
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMP_DIR="$SCRIPT_DIR/.gen_tmp"
+PACKAGE_NAME="oasgospice"
+
+# Use VERSION env var if set, otherwise extract from doc.go
+if [ -z "$VERSION" ]; then
+  VERSION=$(sed -n 's/^var Version = "\(.*\)"$/\1/p' "$SCRIPT_DIR/doc.go")
+fi
+if [ -z "$VERSION" ]; then
+  echo "Error: Could not determine version from VERSION env var or doc.go"
+  exit 1
+fi
+
+# Download openapi.json from GitHub
+# Try tags first (for versions like v1.11.0-rc.3), then branches (for trunk, main, etc.)
+OPENAPI_URL_TAG="https://raw.githubusercontent.com/spiceai/spiceai/refs/tags/${VERSION}/.schema/openapi.json"
+OPENAPI_URL_BRANCH="https://raw.githubusercontent.com/spiceai/spiceai/refs/heads/${VERSION}/.schema/openapi.json"
+
+echo "Downloading OpenAPI spec for version: $VERSION"
+if curl -fsSL "$OPENAPI_URL_TAG" -o "$SCRIPT_DIR/openapi.json" 2>/dev/null; then
+  echo "Downloaded from tag: $OPENAPI_URL_TAG"
+elif curl -fsSL "$OPENAPI_URL_BRANCH" -o "$SCRIPT_DIR/openapi.json" 2>/dev/null; then
+  echo "Downloaded from branch: $OPENAPI_URL_BRANCH"
+else
+  echo "Error: Failed to download openapi.json from tag or branch"
+  exit 1
+fi
+
+# Clean up temp dir
+rm -rf "$TEMP_DIR"
+mkdir -p "$TEMP_DIR"
+
+# TODO: remove (--skip-validate-spec) once the spec is fixed
+
+docker run --rm \
+  -v "$SCRIPT_DIR":/local \
+  openapitools/openapi-generator-cli generate \
+  -i /local/openapi.json \
+  -g go \
+  -o /local/.gen_tmp \
+  --skip-validate-spec \
+  --global-property=models,modelDocs=false,supportingFiles=utils.go \
+  --additional-properties=enumClassPrefix=true,packageName=$PACKAGE_NAME
+
+# Clean up unwanted generated files/folders
+rm -rf "$TEMP_DIR/api" "$TEMP_DIR/.openapi-generator"
+rm -f "$SCRIPT_DIR/openapi.json"
+
+# Combine all model_*.go files into models.gen.go
+echo "package $PACKAGE_NAME" > "$TEMP_DIR/models.gen.go"
+echo "" >> "$TEMP_DIR/models.gen.go"
+
+# Collect all imports from model files
+imports=""
+for f in "$TEMP_DIR"/model_*.go; do
+  [ -f "$f" ] || continue
+  # Extract import lines (between "import (" and ")")
+  imports="$imports$(sed -n '/^import ($/,/^)$/p' "$f" | grep -v '^import ($' | grep -v '^)$')"$'\n'
+done
+
+# Deduplicate and write imports
+if [ -n "$imports" ]; then
+  echo "import (" >> "$TEMP_DIR/models.gen.go"
+  echo "$imports" | sort -u | grep -v '^$' >> "$TEMP_DIR/models.gen.go"
+  echo ")" >> "$TEMP_DIR/models.gen.go"
+  echo "" >> "$TEMP_DIR/models.gen.go"
+fi
+
+# Append model contents (skip package and import lines)
+for f in "$TEMP_DIR"/model_*.go; do
+  [ -f "$f" ] || continue
+  echo "// --- $(basename "$f") ---" >> "$TEMP_DIR/models.gen.go"
+  # Skip package line and import block, keep the rest
+  sed '/^package /d; /^import ($/,/^)$/d; /^import "/d' "$f" >> "$TEMP_DIR/models.gen.go"
+  echo "" >> "$TEMP_DIR/models.gen.go"
+done
+
+# Remove individual model files
+rm -f "$TEMP_DIR"/model_*.go
+
+# Rename utils.go to utils.gen.go
+if [ -f "$TEMP_DIR/utils.go" ]; then
+  mv "$TEMP_DIR/utils.go" "$TEMP_DIR/utils.gen.go"
+fi
+
+# Append custom type fixes from utils_fix.go (skip package/import lines)
+if [ -f "$SCRIPT_DIR/utils_fix.go" ]; then
+  tail -n +4 "$SCRIPT_DIR/utils_fix.go" >> "$TEMP_DIR/utils.gen.go"
+fi
+
+# Remove old generated files from target dir
+rm -f "$SCRIPT_DIR"/*.gen.go
+
+# Move generated files to target dir
+mv "$TEMP_DIR"/*.gen.go "$SCRIPT_DIR/"
+
+# Clean up
+rm -rf "$TEMP_DIR"
+
+echo "Generation complete!"
diff --git a/openapi/doc.go b/openapi/doc.go
@@ -0,0 +1,5 @@
+//go:generate ./client.sh
+
+package oasgospice
+
+var Version = "v1.11.0-rc.3"
diff --git a/openapi/go.mod b/openapi/go.mod
@@ -0,0 +1,7 @@
+module github.com/spiceai/gospice/openapi
+
+go 1.24.0
+
+toolchain go1.24.4
+
+require gopkg.in/validator.v2 v2.0.1
diff --git a/openapi/go.sum b/openapi/go.sum
@@ -0,0 +1,8 @@
+github.com/kr/pretty v0.2.1 h1:Fmg33tUaq4/8ym9TJN1x7sLJnHVwhP33CNkpYV/7rwI=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/validator.v2 v2.0.1 h1:xF0KWyGWXm/LM2G1TrEjqOu4pa6coO9AlWSf3msVfDY=
+gopkg.in/validator.v2 v2.0.1/go.mod h1:lIUZBlB3Im4s/eYp39Ry/wkR02yOPhZ9IwIRBjuPuG8=