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>

Author: RobertoPrevato

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,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",
     [