Add OpenAPI schema validation to CI and local dev (#1817)

Author: mabashian

.github/workflows/code_coverage.yml

@@ -136,3 +136,13 @@ jobs:
         make update-openapi-schema
         git diff --exit-code -- tools/openapi-schema/ansible-ai-connect-service.yaml
         git diff --exit-code -- tools/openapi-schema/ansible-ai-connect-service.json
+
+    - name: Validate OpenAPI schema
+      continue-on-error: true
+      run: |
+        python3 -c "
+        from openapi_spec_validator import validate_url
+        from openapi_spec_validator.validation.validators import OpenAPIV30SpecValidator
+
+        validate_url('http://localhost:8000/api/schema/', cls=OpenAPIV30SpecValidator)
+        "

Makefile

@@ -93,6 +93,12 @@ update-openapi-schema:
 	curl -X GET http://localhost:8000/api/schema/ -o tools/openapi-schema/ansible-ai-connect-service.yaml
 	curl -w "\n" -X GET "http://localhost:8000/api/schema/?format=json" > tools/openapi-schema/ansible-ai-connect-service.json
 
+.PHONY: validate-openapi-schema
+# Validate OpenAPI schema against OpenAPI 3.0 specification (requires server to be running)
+validate-openapi-schema:
+	@echo "Validating OpenAPI schema at http://localhost:8000/api/schema/ ..."
+	@python3 -c "from openapi_spec_validator import validate_url; from openapi_spec_validator.validation.validators import OpenAPIV30SpecValidator; validate_url('http://localhost:8000/api/schema/', cls=OpenAPIV30SpecValidator); print('✓ OpenAPI schema is valid!')"
+
 .PHONY: docker-compose-clean
 docker-compose-clean:
 	${COMPOSE_RUNTIME} -f ${PWD}/tools/docker-compose/compose.yaml down

README.md

@@ -386,6 +386,25 @@ with the following steps:
 3. Run `make update-openapi-schema` in the project root.
 4. Commit the updated OpenAPI Schema YAML file with your API changes.
 
+#### OpenAPI Schema Validation
+
+The OpenAPI schema is automatically validated against the OpenAPI 3.0 specification in CI/CD on every PR and push to main. This ensures the schema remains compliant and catches issues early.
+
+To validate the schema locally before pushing:
+
+```bash
+# Install the validator (included in dev dependencies)
+pip install .[dev]
+
+# Start the development server (in one terminal)
+make run-server
+
+# In another terminal, run the validation
+make validate-openapi-schema
+```
+
+**Note:** Schema validation is currently non-blocking in CI/CD, meaning PRs will not be blocked by validation failures. However, validation errors will be visible in the CI logs and should be addressed.
+
 Also a dynamically generated OpenAPI 3.0 Schema YAML file can be downloaded either:
 
 - Click the /api/schema/ link on Swagger UI, or

pyproject.toml

@@ -70,6 +70,7 @@ dev = [
   'flake8~=6.0.0',
   'grpcio-tools~=1.68.1',
   'isort~=5.10.1',
+  'openapi-spec-validator',
   'pre-commit',
   'responses~=0.24.1',
   'torch-model-archiver',

requirements.txt

@@ -425,7 +425,7 @@ pyyaml==6.0.3
     #   pydrive2
     #   tablib
     #   yamllint
-referencing==0.37.0
+referencing==0.36.2
     # via
     #   ansible-lint
     #   jsonschema