Skip to content

feat: enable semantic versioning for openAPI specs #677

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mpryahin wants to merge 5 commits into from
Closed

feat: enable semantic versioning for openAPI specs #677

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
645b926
Parametrise openapi.yaml
mpryahin Jul 10, 2025
2a7da0d
Parametrise openapi.yaml
mpryahin Jul 10, 2025
4af8dfc
Parametrise openapi.yaml
mpryahin Jul 10, 2025
62000f5
Parametrise openapi.yaml
mpryahin Jul 10, 2025
ebca5a1
add openapi spec compilation target
mpryahin Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/rest_api/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
include ../../Makefile.shared

RESTAPI_BUILD_DIR := ${TARGET_DIR}/rest_api

.PHONY: build

# Replaces all ${TAG} placeholders with the current build version
build:
@echo "Building REST API..."
@mkdir -p $(RESTAPI_BUILD_DIR)

@echo "Copying source files..."
@rsync -av --exclude='Makefile' --exclude='.build' . $(RESTAPI_BUILD_DIR)

@echo "Processing OpenAPI specifications..."
@for file in openapi.yaml openapi_internal.yaml; do \
echo "Processing $$file..."; \
TAG=$(TAG) envsubst '$$TAG' < $(RESTAPI_BUILD_DIR)/$$file > $(RESTAPI_BUILD_DIR)/$$file.tmp; \
mv $(RESTAPI_BUILD_DIR)/$$file.tmp $(RESTAPI_BUILD_DIR)/$$file; \
done

@echo "Build complete"
2 changes: 1 addition & 1 deletion docs/rest_api/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
openapi: "3.1.0"
info:
version: 2.12.0
version: ${TAG}
title: Intel® Geti™ REST API
description: REST API documentation for Intel® Geti™.

Expand Down
2 changes: 1 addition & 1 deletion docs/rest_api/openapi_internal.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
openapi: "3.1.0"
info:
version: 2.12.0
version: ${TAG}
Copy link
Copy Markdown
Contributor

@leoll2 leoll2 Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BDD tests depend on openapi_internal.yaml to generate the JSON spec (source). I checked this branch and the API client auto-generation still succeeds even if the ${TAG} is not resolved in the JSON file:
image

I don't know if this has side effects on the BDD tests, though. Could you please run them on this PR?

Copy link
Copy Markdown
Contributor Author

@mpryahin mpryahin Jul 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Leo, I've implemented an additional target that compiles the OpenAPI spec before generating a client, but given that the compiled code is generated in a subfolder, the hardcoded references to the object schemas break. So the idea of version generation will not work for this OpenAPI spec. I'm closing the PR.
image

title: Intel® Geti™ REST API
description: REST API documentation for Intel® Geti™.

Expand Down
18 changes: 15 additions & 3 deletions interactive_ai/tests/e2e/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,28 @@
MAKEFILE_DIR := $(shell pwd)
OPENAPI_YAML_SPEC := ../../../docs/rest_api/openapi_internal.yaml

OPENAPI_DIR := ../../../docs/rest_api

OPENAPI_YAML_SPEC := $(OPENAPI_DIR)/.build/rest_api/openapi_internal.yaml
OPENAPI_JSON_SPEC := /tmp/openapi_internal.json
CLIENT_NAME := geti_client
CLIENT_PATH := rest_client
SPEC_HASH_FILE := .openapi_spec_hash

.PHONY: all check_yaml_spec generate_json_spec generate_client generate_client_if_needed test test_wip test_smoke mypy
.PHONY: all check_yaml_spec generate_json_spec generate_client generate_client_if_needed test test_wip test_smoke mypy compile_yaml_spec

venv:
$(MAKE) generate_client_if_needed;
uv sync --frozen ${PIP_INSTALL_PARAMS}
check_yaml_spec:

compile_yaml_spec:
@if [ ! -d $(OPENAPI_DIR) ]; then \
echo "Error: OpenAPI directory not found at $(OPENAPI_DIR)"; \
exit 1; \
else \
$(MAKE) -C $(OPENAPI_DIR) build; \
fi

check_yaml_spec: compile_yaml_spec
@if [ ! -f $(OPENAPI_YAML_SPEC) ]; then \
echo "Error: OpenAPI YAML spec file not found at $(OPENAPI_YAML_SPEC)"; \
exit 1; \
Expand Down
14 changes: 12 additions & 2 deletions web_ui/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,23 @@
FROM node:22.12-bookworm-slim@sha256:35531c52ce27b6575d69755c73e65d4468dba93a25644eed56dc12879cae9213 AS build_rest_api_specs

ARG LOCATION=/home/app/rest-api-specs/
ARG REACT_APP_GETI_VERSION=development

WORKDIR ${LOCATION}

COPY --link ./package.json .
COPY --link --from=docs_context rest_api /home/app/docs/rest_api/
COPY --link --from=api_context schemas /home/app/interactive_ai/services/api/schemas/

# Install envsubst
RUN apt-get update && apt-get install -y gettext-base && rm -rf /var/lib/apt/lists/*

# Replace ${TAG} placeholders with the current build version
RUN TAG=${REACT_APP_GETI_VERSION} envsubst '$$TAG' < /home/app/docs/rest_api/openapi.yaml > /home/app/docs/rest_api/openapi.yaml.tmp && \
mv /home/app/docs/rest_api/openapi.yaml.tmp /home/app/docs/rest_api/openapi.yaml && \
TAG=${REACT_APP_GETI_VERSION} envsubst '$$TAG' < /home/app/docs/rest_api/openapi_internal.yaml > /home/app/docs/rest_api/openapi_internal.yaml.tmp && \
mv /home/app/docs/rest_api/openapi_internal.yaml.tmp /home/app/docs/rest_api/openapi_internal.yaml
Comment on lines +22 to +25
Copy link
Copy Markdown
Contributor

@MarkRedeman MarkRedeman Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could simplify this a bit using tee,

RUN for file in /home/app/docs/rest_api/openapi.yaml /home/app/docs/rest_api/openapi_internal.yaml; do \
      TAG=${REACT_APP_GETI_VERSION} envsubst '$$TAG' < "$file" | tee "$file"; \
    done


RUN npm run build:rest-openapi-spec


Expand Down Expand Up @@ -43,8 +53,8 @@ COPY --link ./dev-proxy.ts ./
COPY --link src/ src/
COPY --link public/ public/

COPY --from=docs_context rest_api /home/app/docs/rest_api/
COPY --from=api_context schemas /home/app/interactive_ai/services/api/schemas/
COPY --from=build_rest_api_specs /home/app/docs/rest_api/ /home/app/docs/rest_api/
COPY --from=build_rest_api_specs /home/app/interactive_ai/services/api/schemas/ /home/app/interactive_ai/services/api/schemas/
Comment on lines -46 to +57
Copy link
Copy Markdown
Contributor

@MarkRedeman MarkRedeman Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe we can remove these since we don't need this at build time (only when calling build:rest-openapi-spec).


RUN npm run build

Expand Down
Loading