Fix bug in handling datetimes in examples (#25)

Author: RobertoPrevato

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.6] - 2023-03-18
+- Fixes a bug happening when trying to serialize examples in JSON, when they
+  contain datetimes and are provided in YAML.
+  ([bug report](https://github.com/Neoteroi/mkdocs-plugins/issues/35)).
+
 ## [1.0.5] - 2022-12-22 :santa:
 - Fixes [#22](https://github.com/Neoteroi/essentials-openapi/issues/22)
 

openapidocs/__init__.py

@@ -1 +1 @@
-VERSION = "1.0.5"
+VERSION = "1.0.6"

openapidocs/common.py

@@ -1,6 +1,5 @@
 import base64
 import copy
-import json
 from abc import ABC, abstractmethod
 from dataclasses import asdict, fields, is_dataclass
 from datetime import date, datetime, time
@@ -9,7 +8,9 @@
 from uuid import UUID
 
 import yaml
-from essentials.json import FriendlyEncoder
+from essentials.json import dumps
+
+from openapidocs.mk.contents import OADJSONEncoder
 
 
 class Format(Enum):
@@ -150,9 +151,7 @@ def to_obj(self, item: Any) -> Any:
         return self._get_item_dictionary(item)
 
     def to_json(self, item: Any) -> str:
-        return json.dumps(
-            self.to_obj(item), indent=4, ensure_ascii=False, cls=FriendlyEncoder
-        )
+        return dumps(self.to_obj(item), indent=4, cls=OADJSONEncoder)
 
     def to_yaml(self, item: Any) -> str:
         rep = yaml.dump(

openapidocs/mk/contents.py

@@ -1,10 +1,28 @@
 """
 This module contains classes to generate representations of content types by mime type.
 """
-import json
+import os
 from abc import ABC, abstractmethod
+from datetime import datetime
+from json import JSONEncoder
 from urllib.parse import urlencode
 
+from essentials.json import FriendlyEncoder, dumps
+
+
+class OADJSONEncoder(JSONEncoder):
+    def default(self, obj):
+        try:
+            return JSONEncoder.default(self, obj)
+        except TypeError:
+            if isinstance(obj, datetime):
+                datetime_format = os.environ.get("OPENAPI_DATETIME_FORMAT")
+                if datetime_format:
+                    return obj.strftime(datetime_format)
+                else:
+                    return obj.isoformat()
+            return FriendlyEncoder.default(self, obj)  # type: ignore
+
 
 class ContentWriter(ABC):
     """
@@ -30,7 +48,7 @@ def handle_content_type(self, content_type: str) -> bool:
         return "json" in content_type.lower()
 
     def write(self, value) -> str:
-        return json.dumps(value, ensure_ascii=False, indent=4)
+        return dumps(value, indent=4, cls=OADJSONEncoder)
 
 
 class FormContentWriter(ContentWriter):

tests/test_mk.py

@@ -1,7 +1,11 @@
+from datetime import date
+
 import pytest
 
 from openapidocs.mk import get_http_status_phrase, read_dict
 from openapidocs.mk.common import is_array_schema, is_object_schema
+from openapidocs.mk.contents import JSONContentWriter
+from openapidocs.mk.md import normalize_link
 
 
 def test_get_http_status_phrase():
@@ -34,3 +38,25 @@ def test_is_object_schema():
     assert is_object_schema(1) is False
     assert is_object_schema({}) is False
     assert is_object_schema({"type": "object", "properties": {}}) is True
+
+
+def test_normalize_link_raises():
+    with pytest.raises(ValueError):
+        normalize_link(None)  # type: ignore
+
+    with pytest.raises(ValueError):
+        normalize_link("")
+
+
+def test_content_writer_dates():
+    writer = JSONContentWriter()
+
+    expected_value = """
+{
+    "date": "1986-05-30"
+}
+    """.strip()
+
+    value = writer.write({"date": date(1986, 5, 30)})
+
+    assert value == expected_value

tests/test_v3.py

@@ -1,3 +1,4 @@
+import os
 from abc import abstractmethod
 from dataclasses import dataclass
 from datetime import date, datetime, time
@@ -7,9 +8,11 @@
 from uuid import UUID
 
 import pytest
+import yaml
 from pydantic import BaseModel
 
 from openapidocs.common import Format, Serializer
+from openapidocs.mk.contents import JSONContentWriter
 from openapidocs.v3 import (
     APIKeySecurity,
     Callback,
@@ -2293,3 +2296,110 @@ def test_equality(example_type: Type[TestItem]) -> None:
     one = example.get_instance()
     two = example.get_instance()
     assert one == two
+
+
+def test_serialize_datetimes_examples():
+    """
+    Tests serialization using the default formatter for datetime.
+    """
+    writer = JSONContentWriter()
+
+    yaml_text = """
+description: Start time stamp of the returned data interval
+example: 2022-08-17T18:00:00Z
+in: query
+name: fromInstant
+required: false
+schema:
+    format: date-time
+    type: string
+    """
+    data = yaml.safe_load(yaml_text)
+    json_text = writer.write(data)
+
+    expected_json = """
+{
+    "description": "Start time stamp of the returned data interval",
+    "example": "2022-08-17T18:00:00+00:00",
+    "in": "query",
+    "name": "fromInstant",
+    "required": false,
+    "schema": {
+        "format": "date-time",
+        "type": "string"
+    }
+}
+    """.strip()
+
+    assert json_text == expected_json
+
+
+def test_serialize_datetimes_examples_exact_format():
+    writer = JSONContentWriter()
+
+    yaml_text = """
+description: Start time stamp of the returned data interval
+example: '2022-08-17T18:00:00Z'
+in: query
+name: fromInstant
+required: false
+schema:
+    format: date-time
+    type: string
+    """
+    data = yaml.safe_load(yaml_text)
+    json_text = writer.write(data)
+
+    expected_json = """
+{
+    "description": "Start time stamp of the returned data interval",
+    "example": "2022-08-17T18:00:00Z",
+    "in": "query",
+    "name": "fromInstant",
+    "required": false,
+    "schema": {
+        "format": "date-time",
+        "type": "string"
+    }
+}
+    """.strip()
+
+    assert json_text == expected_json
+
+
+def test_serialize_datetimes_examples_exact_format_env():
+    os.environ["OPENAPI_DATETIME_FORMAT"] = "%Y-%m-%dT%H:%M:%SZ"
+
+    try:
+        writer = JSONContentWriter()
+
+        yaml_text = """
+    description: Start time stamp of the returned data interval
+    example: 2022-08-17T18:00:00Z
+    in: query
+    name: fromInstant
+    required: false
+    schema:
+        format: date-time
+        type: string
+        """
+        data = yaml.safe_load(yaml_text)
+        json_text = writer.write(data)
+
+        expected_json = """
+{
+    "description": "Start time stamp of the returned data interval",
+    "example": "2022-08-17T18:00:00Z",
+    "in": "query",
+    "name": "fromInstant",
+    "required": false,
+    "schema": {
+        "format": "date-time",
+        "type": "string"
+    }
+}
+        """.strip()
+
+        assert json_text == expected_json
+    finally:
+        os.environ["OPENAPI_DATETIME_FORMAT"] = ""