Remove null as a data type in OpenAPI 3.0; replace it with nullable

Also add some docstrings to compat.py for clarity.

Author: hathawsh

openapi_pydantic/compat.py

@@ -4,6 +4,18 @@
 
 from pydantic.version import VERSION as PYDANTIC_VERSION
 
+__all__ = [
+    "PYDANTIC_V2",
+    "ConfigDict",
+    "JsonSchemaMode",
+    "models_json_schema",
+    "RootModel",
+    "Extra",
+    "v1_schema",
+    "DEFS_KEY",
+    "min_length_arg",
+]
+
 PYDANTIC_MAJOR_VERSION = int(PYDANTIC_VERSION.split(".", 1)[0])
 PYDANTIC_V2 = PYDANTIC_MAJOR_VERSION >= 2
 
@@ -21,15 +33,18 @@ def ConfigDict(
         json_schema_extra: dict[str, Any] | None = None,
         populate_by_name: bool = True,
     ) -> PydanticConfigDict:
+        """Stub for pydantic.ConfigDict in Pydantic 2"""
         ...
 
     class Extra(Enum):
+        """Stub for pydantic.Extra in Pydantic 1"""
+
         allow = "allow"
         ignore = "ignore"
         forbid = "forbid"
 
     class RootModel(BaseModel):
-        ...
+        """Stub for pydantic.RootModel in Pydantic 2"""
 
     JsonSchemaMode = Literal["validation", "serialization"]
 
@@ -38,7 +53,9 @@ def models_json_schema(
         *,
         by_alias: bool = True,
         ref_template: str = "#/$defs/{model}",
+        schema_generator: type | None = None,
     ) -> tuple[dict, dict[str, Any]]:
+        """Stub for pydantic.json_schema.models_json_schema in Pydantic 2"""
         ...
 
     def v1_schema(
@@ -47,6 +64,7 @@ def v1_schema(
         by_alias: bool = True,
         ref_prefix: str = "#/$defs",
     ) -> dict[str, Any]:
+        """Stub for pydantic.schema.schema in Pydantic 1"""
         ...
 
     DEFS_KEY = "$defs"
@@ -55,10 +73,11 @@ class MinLengthArg(TypedDict):
         pass
 
     def min_length_arg(min_length: int) -> MinLengthArg:
+        """Generate a min_length or min_items parameter for Field(...)"""
         ...
 
 elif PYDANTIC_V2:
-    from typing import Literal, TypedDict
+    from typing import TypedDict
 
     from pydantic import ConfigDict, RootModel
     from pydantic.json_schema import JsonSchemaMode, models_json_schema
@@ -72,7 +91,7 @@ class MinLengthArg(TypedDict):
     def min_length_arg(min_length: int) -> MinLengthArg:
         return {"min_length": min_length}
 
-    # Create V1 stubs
+    # Create V1 stubs, These should not be used when PYDANTIC_V2 is true.
     Extra = None
     v1_schema = None
 
@@ -92,23 +111,8 @@ class MinLengthArg(TypedDict):
     def min_length_arg(min_length: int) -> MinLengthArg:
         return {"min_items": min_length}
 
-    # Create V2 stubs
+    # Create V2 stubs. These should not be used when PYDANTIC_V2 is false.
     ConfigDict = None
-    Literal = None
     models_json_schema = None
     JsonSchemaMode = None
     RootModel = None
-
-
-__all__ = [
-    "PYDANTIC_V2",
-    "Literal",
-    "ConfigDict",
-    "JsonSchemaMode",
-    "models_json_schema",
-    "RootModel",
-    "Extra",
-    "v1_schema",
-    "DEFS_KEY",
-    "min_length_arg",
-]

openapi_pydantic/util.py

@@ -104,22 +104,23 @@ def construct_open_api_with_schema_class(
                     f'"{existing_key}" already exists in {ref_prefix}. '
                     f'The value of "{ref_prefix}{existing_key}" will be overwritten.'
                 )
-        new_open_api.components.schemas.update(
-            {
-                key: schema_validate(schema_dict)
-                for key, schema_dict in schema_definitions[DEFS_KEY].items()
-            }
-        )
+        new_open_api.components.schemas.update(_validate_schemas(schema_definitions))
     else:
-        for key, schema_dict in schema_definitions[DEFS_KEY].items():
-            schema_validate(schema_dict)
-        new_open_api.components.schemas = {
-            key: schema_validate(schema_dict)
-            for key, schema_dict in schema_definitions[DEFS_KEY].items()
-        }
+        new_open_api.components.schemas = _validate_schemas(schema_definitions)
     return new_open_api
 
 
+def _validate_schemas(schema_definitions: dict[str, Any]) -> dict[str, Schema]:
+    """Convert JSON Schema definitions to parsed OpenAPI objects"""
+    # Note: if an error occurs in schema_validate(), it may indicate that
+    # the generated JSON schemas are not compatible with the version
+    # of OpenAPI this module depends on.
+    return {
+        key: schema_validate(schema_dict)
+        for key, schema_dict in schema_definitions[DEFS_KEY].items()
+    }
+
+
 def _handle_pydantic_schema(open_api: OpenAPI) -> List[Type[BaseModel]]:
     """
     This function traverses the `OpenAPI` object and

openapi_pydantic/v3/v3_0_3/datatype.py

@@ -2,9 +2,11 @@
 
 
 class DataType(str, enum.Enum):
-    """Data type of an object."""
+    """Data type of an object.
+
+    Note: OpenAPI 3.0.x does not support null as a data type.
+    """
 
-    NULL = "null"
     STRING = "string"
     NUMBER = "number"
     INTEGER = "integer"

openapi_pydantic/v3/v3_0_3/header.py

@@ -2,7 +2,7 @@
 
 from pydantic import Field
 
-from openapi_pydantic.compat import PYDANTIC_V2, ConfigDict, Extra, Literal
+from openapi_pydantic.compat import PYDANTIC_V2, ConfigDict, Extra
 
 from .parameter import Parameter, ParameterLocation
 
@@ -34,6 +34,8 @@ class Header(Parameter):
         )
 
 elif PYDANTIC_V2:
+    from typing import Literal
+
     LiteralEmptyString = Literal[""]
 
     class Header(Parameter):

openapi_pydantic/v3/v3_0_3/util.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Any, Generic, List, Optional, Set, Type, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, List, Optional, Set, Type, TypeVar, cast
 
 from pydantic import BaseModel
 
@@ -44,6 +44,36 @@ def get_mode(
     return cast(JsonSchemaMode, mode)
 
 
+if TYPE_CHECKING:
+
+    class GenerateOpenAPI30Schema:
+        ...
+
+elif PYDANTIC_V2:
+    from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+    from pydantic_core import core_schema
+
+    class GenerateOpenAPI30Schema(GenerateJsonSchema):
+        """Modify the schema generation for OpenAPI 3.0.
+
+        In OpenAPI 3.0, types can not be None, but a special "nullable"
+        field is available.
+        """
+
+        def nullable_schema(
+            self,
+            schema: core_schema.NullableSchema,
+        ) -> JsonSchemaValue:
+            inner_json_schema = self.generate_inner(schema["schema"])
+            inner_json_schema["nullable"] = True
+            return inner_json_schema
+
+else:
+
+    class GenerateOpenAPI30Schema:
+        ...
+
+
 def construct_open_api_with_schema_class(
     open_api: OpenAPI,
     schema_classes: Optional[List[Type[BaseModel]]] = None,
@@ -89,6 +119,7 @@ def construct_open_api_with_schema_class(
             [(c, get_mode(c)) for c in schema_classes],
             by_alias=by_alias,
             ref_template=ref_template,
+            schema_generator=GenerateOpenAPI30Schema,
         )
     else:
         schema_definitions = v1_schema(
@@ -104,22 +135,25 @@ def construct_open_api_with_schema_class(
                     f'"{existing_key}" already exists in {ref_prefix}. '
                     f'The value of "{ref_prefix}{existing_key}" will be overwritten.'
                 )
-        new_open_api.components.schemas.update(
-            {
-                key: schema_validate(schema_dict)
-                for key, schema_dict in schema_definitions[DEFS_KEY].items()
-            }
-        )
+        new_open_api.components.schemas.update(_validate_schemas(schema_definitions))
     else:
-        for key, schema_dict in schema_definitions[DEFS_KEY].items():
-            schema_validate(schema_dict)
-        new_open_api.components.schemas = {
-            key: schema_validate(schema_dict)
-            for key, schema_dict in schema_definitions[DEFS_KEY].items()
-        }
+        new_open_api.components.schemas = _validate_schemas(schema_definitions)
     return new_open_api
 
 
+def _validate_schemas(
+    schema_definitions: dict[str, Any]
+) -> dict[str, Reference | Schema]:
+    """Convert JSON Schema definitions to parsed OpenAPI objects"""
+    # Note: if an error occurs in schema_validate(), it may indicate that
+    # the generated JSON schemas are not compatible with the version
+    # of OpenAPI this module depends on.
+    return {
+        key: schema_validate(schema_dict)
+        for key, schema_dict in schema_definitions[DEFS_KEY].items()
+    }
+
+
 def _handle_pydantic_schema(open_api: OpenAPI) -> List[Type[BaseModel]]:
     """
     This function traverses the `OpenAPI` object and

openapi_pydantic/v3/v3_1_0/header.py

@@ -2,7 +2,7 @@
 
 from pydantic import Field
 
-from openapi_pydantic.compat import PYDANTIC_V2, ConfigDict, Extra, Literal
+from openapi_pydantic.compat import PYDANTIC_V2, ConfigDict, Extra
 
 from .parameter import Parameter, ParameterLocation
 
@@ -33,6 +33,8 @@ class Header(Parameter):
         )
 
 elif PYDANTIC_V2:
+    from typing import Literal
+
     LiteralEmptyString = Literal[""]
 
     class Header(Parameter):