Merge pull request #803 from marshmallow-code/make_validate_spec_private_api

Remove validate_spec from public API

Author: lafrech

src/apispec/utils.py

@@ -5,13 +5,6 @@
 from __future__ import annotations
 
 import re
-import json
-import typing
-
-from apispec import exceptions
-
-if typing.TYPE_CHECKING:
-    from apispec.core import APISpec
 
 
 COMPONENT_SUBSECTIONS = {
@@ -50,37 +43,6 @@ def build_reference(
     }
 
 
-def validate_spec(spec: APISpec) -> bool:
-    """Validate the output of an :class:`APISpec` object against the
-    OpenAPI specification.
-
-    Note: Requires installing apispec with the ``[validation]`` extras.
-    ::
-
-        pip install 'apispec[validation]'
-
-    :raise: apispec.exceptions.OpenAPIError if validation fails.
-    """
-    try:
-        import prance
-    except ImportError as error:  # re-raise with a more verbose message
-        exc_class = type(error)
-        raise exc_class(
-            "validate_spec requires prance to be installed. "
-            "You can install all validation requirements using:\n"
-            "    pip install 'apispec[validation]'"
-        ) from error
-    parser_kwargs = {}
-    if spec.openapi_version.major == 3:
-        parser_kwargs["backend"] = "openapi-spec-validator"
-    try:
-        prance.BaseParser(spec_string=json.dumps(spec.to_dict()), **parser_kwargs)
-    except prance.ValidationError as err:
-        raise exceptions.OpenAPIError(*err.args) from err
-    else:
-        return True
-
-
 # from django.contrib.admindocs.utils
 def trim_docstring(docstring: str) -> str:
     """Uniformly trims leading/trailing whitespace from docstrings.

tests/test_ext_marshmallow_openapi.py

@@ -1,13 +1,14 @@
-import pytest
 from datetime import datetime
 
+import pytest
+
 from marshmallow import EXCLUDE, fields, INCLUDE, RAISE, Schema, validate
 
 from apispec.ext.marshmallow import MarshmallowPlugin
-from apispec import exceptions, utils, APISpec
+from apispec import exceptions, APISpec
 
 from .schemas import CustomList, CustomStringField
-from .utils import get_schemas, build_ref
+from .utils import get_schemas, build_ref, validate_spec
 
 
 class TestMarshmallowFieldToOpenAPI:
@@ -533,7 +534,7 @@ def test_openapi_tools_validate_v2():
         },
     )
     try:
-        utils.validate_spec(spec)
+        validate_spec(spec)
     except exceptions.OpenAPIError as error:
         pytest.fail(str(error))
 
@@ -602,7 +603,7 @@ def test_openapi_tools_validate_v3():
         },
     )
     try:
-        utils.validate_spec(spec)
+        validate_spec(spec)
     except exceptions.OpenAPIError as error:
         pytest.fail(str(error))
 

tests/utils.py

@@ -1,5 +1,8 @@
 """Utilities to get elements of generated spec"""
+import json
 
+from apispec.core import APISpec
+from apispec import exceptions
 from apispec.utils import build_reference
 
 
@@ -43,3 +46,34 @@ def get_paths(spec):
 
 def build_ref(spec, component_type, obj):
     return build_reference(component_type, spec.openapi_version.major, obj)
+
+
+def validate_spec(spec: APISpec) -> bool:
+    """Validate the output of an :class:`APISpec` object against the
+    OpenAPI specification.
+
+    Note: Requires installing apispec with the ``[validation]`` extras.
+    ::
+
+        pip install 'apispec[validation]'
+
+    :raise: apispec.exceptions.OpenAPIError if validation fails.
+    """
+    try:
+        import prance
+    except ImportError as error:  # re-raise with a more verbose message
+        exc_class = type(error)
+        raise exc_class(
+            "validate_spec requires prance to be installed. "
+            "You can install all validation requirements using:\n"
+            "    pip install 'apispec[validation]'"
+        ) from error
+    parser_kwargs = {}
+    if spec.openapi_version.major == 3:
+        parser_kwargs["backend"] = "openapi-spec-validator"
+    try:
+        prance.BaseParser(spec_string=json.dumps(spec.to_dict()), **parser_kwargs)
+    except prance.ValidationError as err:
+        raise exceptions.OpenAPIError(*err.args) from err
+    else:
+        return True