Fix #30 (#67)

* 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>

* Update CHANGELOG.md

* Update test_mk_v3.py

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: RobertoPrevato

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
 

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"] = {}
 

tests/test_mk_v3.py

@@ -52,6 +52,18 @@ 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",
     [