feat: OpenAPI 3.1 support (parsers, generators, comprehensive tests) #99

dougborg · 2025-08-10T16:53:10Z

Closes #79

Summary

Adds end-to-end OpenAPI 3.1 support: version detection, dedicated 3.0 & 3.1 parsers, unified model & service code generation, and extensive test coverage.

Key Changes

Version detection utility + separate OpenAPI 3.0 / 3.1 parser modules
Model generator enhancements: refs, composite schemas (allOf / oneOf / anyOf), DataType enums, self-references, import aggregation fix for allOf
Service generator updates: multi-version media/response handling and request body resolution
Generalized generator & api_config for 3.0+ (model_dump usage, shared unions)
Unified core model unions (Operation, PathItem, Schema) enabling cross-version typing
New comprehensive test suites:
- Completeness & schema feature coverage for 3.1
- Negative spec tests (validation & unsupported features)
- Swagger Petstore 3.0 & 3.1 regression fixtures
- Edge cases (self-references, composites, imports)
Tooling: dependency and typing improvements, test fixture additions

Test Status

poetry run pytest -q → 232 passed, 11 xfailed (intentional skips for unsupported 3.1 features not yet implemented)

Follow-ups (separate PRs)

Implement currently xfailed 3.1 features (e.g. unevaluatedProperties, advanced boolean schema behaviors)
Potential type conversion refactor (see Refactor model_generator.type_converter to reduce complexity and improve composite schema handling #98)

Backward Compatibility

No breaking changes for OpenAPI 3.0 users; 3.1 is auto-detected and handled transparently.

Feedback welcome.

…nerate_data)

…nums, composites) and add edge tests; fix allOf import aggregation

…ponse handling) with edge tests

…PI types, model_dump) and update templates

…nions)

…ive generate_data tests and status doc

Copilot

Pull Request Overview

This PR introduces comprehensive OpenAPI 3.1 support with version detection, dedicated parsers for both 3.0 and 3.1, unified code generation, and extensive test coverage for new features and backward compatibility validation.

Key changes include:

Implemented version detection utility with separate parser modules for OpenAPI 3.0/3.1
Enhanced model and service generators with improved schema handling (refs, composites, DataType enums)
Added comprehensive test suites covering feature completeness, edge cases, and regression testing with Swagger Petstore specs
Updated core functionality to use unified model unions enabling cross-version typing

Reviewed Changes

Copilot reviewed 44 out of 47 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`tests/test_version_detector_edges.py`	Tests version detection edge cases and error handling
`tests/test_swagger_petstore_31.py`	Swagger Petstore 3.1 regression tests and code generation validation
`tests/test_swagger_petstore_30.py`	Swagger Petstore 3.0 regression tests for backward compatibility
`tests/test_service_generator_edges.py`	Edge case tests for service generator functionality
`tests/test_openapi_31_*.py`	Comprehensive OpenAPI 3.1 feature coverage and completeness testing
`tests/test_openapi_30.py`	OpenAPI 3.0 specific functionality tests
`tests/test_model_generator_edges.py`	Edge case tests for model generator type conversion
Various test data files	Test fixtures for OpenAPI 3.1 specifications and Swagger Petstore examples
`src/openapi_python_generator/version_detector.py`	Version detection utility for routing to appropriate parsers
`src/openapi_python_generator/parsers/openapi_31.py`	OpenAPI 3.1 specific parser implementation

Copilot · 2025-08-10T16:54:12Z

tests/test_openapi_31_coverage.py

+            },
+        }
+
+        with pytest.raises(Exception):  # Should fail to parse


Using a bare Exception catch is too broad. Consider catching more specific exceptions like ValidationError or pydantic.ValidationError to make the test more precise and meaningful.

Suggested change

with pytest.raises(Exception): # Should fail to parse

with pytest.raises(ValidationError): # Should fail to parse

Copilot · 2025-08-10T16:54:12Z

tests/test_openapi_31_coverage.py

+            },
+        }
+
+        with pytest.raises(Exception):  # Should fail to parse


Using a bare Exception catch is too broad. Consider catching more specific exceptions like ValidationError or pydantic.ValidationError to make the test more precise and meaningful.

Suggested change

with pytest.raises(Exception): # Should fail to parse

with pytest.raises(ValidationError): # Should fail to parse

Copilot · 2025-08-10T16:54:13Z

tests/test_model_generator_edges.py

+def test_type_converter_unknown_list_first_type_fallback():
+    # Invalid enum value in list should raise ValidationError (spec invalid)
+    import pydantic
+    with pytest.raises(pydantic.ValidationError):  # type: ignore[attr-defined]


The type: ignore comment suggests an import issue. Consider importing ValidationError directly from pydantic at the top of the file instead of using pydantic.ValidationError to avoid the type checker warning.

Suggested change

with pytest.raises(pydantic.ValidationError): # type: ignore[attr-defined]

with pytest.raises(ValidationError):

- Merge path-level parameters into operations - Add default tag fallback (fixes None_service filename) - Add path placeholder fallback param injection - Harden requestBody & response schema handling across 3.0/3.1

…ttp; add cross-library 204 tests

…aiohttp/httpx/requests

MarcoMuellner · 2025-08-13T06:35:16Z

This is great! Thank you! I'll review this asap and give you feedback

MarcoMuellner

I generally like the changes - they are also much smaller then i would have assumed. So great work :) I do have some comments - maybe lets resolve those first, before i can approve it?

MarcoMuellner · 2025-08-17T18:32:45Z

src/openapi_python_generator/generate_data.py

+        version = detect_openapi_version(data)
+
+        if version == "3.0":
+            openapi_obj = parse_openapi_30(data)  # type: ignore[assignment]


Not sure why we would ignore the type here?

MarcoMuellner · 2025-08-17T18:33:23Z

src/openapi_python_generator/generate_data.py

+
+    # Use version-specific generator
+    if version == "3.0":
+        result = generate_code_30(


For both function i would prefer to replace . with an underscore, i.e. generate_code_3_0

MarcoMuellner · 2025-08-17T18:35:17Z

src/openapi_python_generator/language_converters/python/service_generator.py

+    if isinstance(reference_obj, Reference30):
+        return MediaType30(schema=reference_obj)
+    elif isinstance(reference_obj, Reference31):
+        return MediaType31(schema=reference_obj)


Similar for these types.

I am also not a 100% sure that this type of abstraction is ... good? It feels a bit icky to do it this way. Rather, i'd have a new type MediaType that within itself does the abstraction for it if you understand what i mean.

This goes for all other objects as well.

MarcoMuellner · 2025-08-17T18:36:55Z

src/openapi_python_generator/language_converters/python/templates/requests.jinja2

    {%- endif %}
 {% else %}
-    return response.json()
+    return body


This does feel a bit dangerous, as it breaks the current way the template works - and may cause isses for users. Is this strictly necessary for this change?

MarcoMuellner · 2025-08-17T18:41:27Z

pyproject.toml

+responses = "^0.25.7"
+types-PyYAML = "^6.0.12.20240808"
+types-requests = "^2.32.0.20241016"
+types-urllib3 = "^1.26.25.14"


please fix this - this doesn't work. Also not sure why this is needed for this change?

MarcoMuellner · 2025-09-08T07:49:30Z

I took the liberty of improving on your work here - thank you doug! Keep them coming :)

Doug Borg added 7 commits August 10, 2025 10:14

chore: tooling updates (deps, type markers, ignore generated output)

b1e1082

feat: add OpenAPI 3.1 support (version detection, parsers, unified ge…

7dc4acc

…nerate_data)

feat: enhance model generator for 3.1 compatibility (refs, DataType e…

c02c968

…nums, composites) and add edge tests; fix allOf import aggregation

feat: update service generator for 3.1 (multi-version types, body/res…

c528b86

…ponse handling) with edge tests

feat: generalize generator & api_config for 3.0+ (multi-version OpenA…

1ac713b

…PI types, model_dump) and update templates

refactor: unify core models for OpenAPI 3.0/3.1 compatibility (type u…

3badf5e

…nions)

test: add OpenAPI 3.1 completeness & schema feature suites plus negat…

75d4bf8

…ive generate_data tests and status doc

Copilot AI review requested due to automatic review settings August 10, 2025 16:53

Copilot AI reviewed Aug 10, 2025

View reviewed changes

Doug Borg added 5 commits August 10, 2025 10:59

tests: tighten 3.1 unsupported feature expectations to ValidationError

4a870be

tests: use direct ValidationError import in model generator edge test

7e42154

tests: remove unused var in 3.1 vs 3.0 comparison and tidy comments

e83960e

feat: improve service generation

1f4f6c7

- Merge path-level parameters into operations - Add default tag fallback (fixes None_service filename) - Add path placeholder fallback param injection - Harden requestBody & response schema handling across 3.0/3.1

feat(templates): skip JSON parsing for 204 across httpx/requests/aioh…

880704b

…ttp; add cross-library 204 tests

This was referenced Aug 10, 2025

Update to more recent version of HTTPX #97

Closed

error with Swagger Editor petstore example #63

Open

Doug Borg added 2 commits August 10, 2025 13:19

chore(templates): unify 204 handling and body variable naming across …

630ffe9

…aiohttp/httpx/requests

feat: improve model docstring header with title fallback + add test

c4e9faf

MarcoMuellner requested changes Aug 17, 2025

View reviewed changes

MarcoMuellner reviewed Aug 17, 2025

View reviewed changes

MarcoMuellner merged commit c4e9faf into MarcoMuellner:main Sep 8, 2025
0 of 6 checks passed

	with pytest.raises(Exception): # Should fail to parse
	with pytest.raises(ValidationError): # Should fail to parse

	with pytest.raises(pydantic.ValidationError): # type: ignore[attr-defined]
	with pytest.raises(ValidationError):

feat: OpenAPI 3.1 support (parsers, generators, comprehensive tests) #99

feat: OpenAPI 3.1 support (parsers, generators, comprehensive tests) #99

Uh oh!

Conversation

dougborg commented Aug 10, 2025

Summary

Key Changes

Test Status

Follow-ups (separate PRs)

Backward Compatibility

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

MarcoMuellner commented Aug 13, 2025

Uh oh!

MarcoMuellner left a comment

Choose a reason for hiding this comment

Uh oh!

MarcoMuellner Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

MarcoMuellner Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

MarcoMuellner Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

MarcoMuellner Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

MarcoMuellner Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

MarcoMuellner Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MarcoMuellner commented Sep 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants