From 2efa55b98b3a1b2467b3fe3318d4b12f090c26ec Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Fri, 6 Mar 2026 20:18:59 +0100 Subject: [PATCH 1/3] Raise clear error for Swagger 2.0 specs (issue #30) Instead of silently producing empty output, detect swagger: '2.0' in normalize_data and raise a ValueError with a link to https://converter.swagger.io/ so users know how to proceed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- openapidocs/mk/v3/__init__.py | 7 +++++++ tests/test_mk_v3.py | 10 ++++++++++ 2 files changed, 17 insertions(+) diff --git a/openapidocs/mk/v3/__init__.py b/openapidocs/mk/v3/__init__.py index 8a02c5c..ccdd9f5 100644 --- a/openapidocs/mk/v3/__init__.py +++ b/openapidocs/mk/v3/__init__.py @@ -237,6 +237,13 @@ def normalize_data(self, data): $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions. """ + if isinstance(data.get("swagger"), str) and data["swagger"].startswith("2"): + raise ValueError( + "Swagger 2.0 specifications are not supported. " + "Please convert your specification to OpenAPI 3.x first. " + "You can use the online converter at https://converter.swagger.io/" + ) + if "components" not in data: data["components"] = {} diff --git a/tests/test_mk_v3.py b/tests/test_mk_v3.py index 0d44fd0..8d3722f 100644 --- a/tests/test_mk_v3.py +++ b/tests/test_mk_v3.py @@ -52,6 +52,16 @@ def test_file_ref_raises_for_missing_file(): ) +def test_swagger2_raises_not_supported(): + """ + Regression test for https://github.com/Neoteroi/essentials-openapi/issues/30 + Swagger 2.0 specs should raise a clear ValueError instead of silently + producing empty output. + """ + with pytest.raises(ValueError, match="Swagger 2.0 specifications are not supported"): + OpenAPIV3DocumentationHandler({"swagger": "2.0", "info": {}, "paths": {}}) + + @pytest.mark.parametrize( "input,expected_result", [ From cd4bb2547e6a0f487abe054aca2c2e5b9cdc3df0 Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Fri, 6 Mar 2026 20:22:19 +0100 Subject: [PATCH 2/3] Update CHANGELOG.md --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6bdbd8b..f36732f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add OAS 3.1 support, cross-version warnings, and fix nullable spacing, by @dcode. - Fix MARKDOWN style table separators to use minimum 3 hyphens (issue #39), reported by @michael-nok. - Fix [#45](https://github.com/Neoteroi/essentials-openapi/issues/45): add support for displaying descriptions of schema properties, reported by @Maia-Everett. +- Fix [#30](https://github.com/Neoteroi/essentials-openapi/issues/30): raise an error + when trying to generate output from an older Swagger v2 specification file (these were + never supported as there was never a `/mk/v2/` namespace, intentionally). ## [1.3.0] - 2025-11-19 From 137b2a8dbc7042b878340d53691ad9dac1c93d65 Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Fri, 6 Mar 2026 20:24:49 +0100 Subject: [PATCH 3/3] Update test_mk_v3.py --- tests/test_mk_v3.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/test_mk_v3.py b/tests/test_mk_v3.py index 8d3722f..ae3e9ea 100644 --- a/tests/test_mk_v3.py +++ b/tests/test_mk_v3.py @@ -58,7 +58,9 @@ def test_swagger2_raises_not_supported(): Swagger 2.0 specs should raise a clear ValueError instead of silently producing empty output. """ - with pytest.raises(ValueError, match="Swagger 2.0 specifications are not supported"): + with pytest.raises( + ValueError, match="Swagger 2.0 specifications are not supported" + ): OpenAPIV3DocumentationHandler({"swagger": "2.0", "info": {}, "paths": {}})