essentials-openapi 1.3.0__tar.gz → 1.4.0__tar.gz

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/CHANGELOG.md

@@ -5,7 +5,34 @@ 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.4.0] - 2026-03-07 :copilot:
+
+- 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).
+- Fix [#35](https://github.com/Neoteroi/essentials-openapi/issues/35): group response
+  codes in a tab group on MkDocs output, reported by @Andre601.
+- Fix [#47](https://github.com/Neoteroi/essentials-openapi/issues/47): remove `wordwrap`
+  filters from all templates as they break links and mermaid chart code blocks in
+  descriptions, reported by @ElementalWarrior.
+- Fix [#49](https://github.com/Neoteroi/essentials-openapi/issues/49): support `$ref`
+  values of the form `file.yaml#/fragment/path` (external file with JSON Pointer
+  fragment), reported by @mbklein.
+- Fix [#55](https://github.com/Neoteroi/essentials-openapi/issues/55): `jsonSchemaDialect`
+  is not required and should not have a default value.
+- Fix [#60](https://github.com/Neoteroi/essentials-openapi/issues/60): resolve `$ref`
+  values in response headers pointing to `#/components/headers/...` to avoid
+  `UndefinedError` when rendering response tables, reported by @copiousfreetime.
+- Fix [#64](https://github.com/Neoteroi/essentials-openapi/issues/64): use `examples`
+  array (JSON Schema draft 6+) as a fallback for auto-generated response examples;
+  also use `enum` values as examples for all scalar types (integer, number, boolean),
+  reported by @jan-ldwg.
+
 ## [1.3.0] - 2025-11-19
+
 - Add support for passing custom Jinja2 templates as an argument, by @sindrehan.
 
 ## [1.2.1] - 2025-07-30

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: essentials-openapi
-Version: 1.3.0
+Version: 1.4.0
 Summary: Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML.
 Project-URL: Homepage, https://github.com/Neoteroi/essentials-openapi
 Project-URL: Bug Tracker, https://github.com/Neoteroi/essentials-openapi/issues

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 VERSION = __version__

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/common.py

@@ -82,6 +82,10 @@ def normalize_dict_factory(items: list[tuple[Any, Any]]) -> dict[str, Any]:
             data["$ref"] = value
             continue
 
+        if key == "defs":
+            data["$defs"] = value
+            continue
+
         for handler in TYPES_HANDLERS:
             value = handler.normalize(value)
 
@@ -129,6 +133,8 @@ def _asdict_inner(obj: Any, dict_factory: Callable[[Any], Any]) -> Any:
             for k, v in obj.items()
         )
     else:
+        for handler in TYPES_HANDLERS:
+            obj = handler.normalize(obj)
         return copy.deepcopy(obj)
 
 

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/common.py

@@ -33,17 +33,29 @@ def is_reference(data: object) -> bool:
     return "$ref" in data
 
 
+def _type_matches(type_val: Any, expected: str) -> bool:
+    """
+    Returns True if type_val equals expected (OAS 3.0 string) or contains expected
+    (OAS 3.1 list).
+    """
+    if isinstance(type_val, list):
+        return expected in type_val
+    return type_val == expected
+
+
 def is_object_schema(data: object) -> bool:
     """
     Returns a value indicating whether the given schema dictionary represents
     an object schema.
 
-    is_reference({"type": "array", "items": {...}}) -> True
+    Supports both OAS 3.0 (type: "object") and OAS 3.1 (type: ["object", ...]).
     """
     if not isinstance(data, dict):
         return False
     data = cast(dict[str, object], data)
-    return data.get("type") == "object" and isinstance(data.get("properties"), dict)
+    return _type_matches(data.get("type"), "object") and isinstance(
+        data.get("properties"), dict
+    )
 
 
 def is_array_schema(data: object) -> bool:
@@ -51,12 +63,14 @@ def is_array_schema(data: object) -> bool:
     Returns a value indicating whether the given schema dictionary represents
     an array schema.
 
-    is_reference({"type": "array", "items": {...}}) -> True
+    Supports both OAS 3.0 (type: "array") and OAS 3.1 (type: ["array", ...]).
     """
     if not isinstance(data, dict):
         return False
     data = cast(dict[str, object], data)
-    return data.get("type") == "array" and isinstance(data.get("items"), dict)
+    return _type_matches(data.get("type"), "array") and isinstance(
+        data.get("items"), dict
+    )
 
 
 def get_ref_type_name(reference: dict[str, str] | str) -> str:

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/jinja.py

@@ -21,6 +21,56 @@ from .common import DocumentsWriter, is_reference
 from .md import normalize_link, write_table
 
 
+def get_primary_type(type_val):
+    """
+    Returns the primary (first non-null) type from a schema type value.
+
+    Handles both OAS 3.0 (string) and OAS 3.1 (list) type representations:
+      - "string"             → "string"
+      - ["string", "null"]   → "string"
+      - ["null"]             → "null"
+      - ["string", "integer"] → "string"
+    """
+    if not type_val:
+        return None
+    if isinstance(type_val, list):
+        non_null = [t for t in type_val if t != "null"]
+        return non_null[0] if non_null else "null"
+    return type_val
+
+
+def is_nullable_schema(schema) -> bool:
+    """
+    Returns True if the given schema is nullable.
+
+    Handles both OAS 3.0 (nullable: true) and OAS 3.1 (type: [..., "null"]) patterns.
+    """
+    if not isinstance(schema, dict):
+        return False
+    if schema.get("nullable"):
+        return True
+    type_val = schema.get("type")
+    if isinstance(type_val, list):
+        return "null" in type_val
+    return False
+
+
+def get_type_display(type_val) -> str:
+    """
+    Returns a display string for a schema type value.
+
+    Handles both OAS 3.0 (string) and OAS 3.1 (list) type representations:
+      - "string"               → "string"
+      - ["string", "null"]     → "string | null"
+      - ["string", "integer"]  → "string | integer"
+    """
+    if not type_val:
+        return ""
+    if isinstance(type_val, list):
+        return " | ".join(str(t) for t in type_val)
+    return str(type_val)
+
+
 def configure_filters(env: Environment):
     env.filters.update(
         {"route": highlight_params, "table": write_table, "link": normalize_link}
@@ -35,6 +85,9 @@ def configure_functions(env: Environment):
         "scalar_types": {"string", "integer", "boolean", "number"},
         "get_http_status_phrase": get_http_status_phrase,
         "write_md_table": write_table,
+        "get_primary_type": get_primary_type,
+        "is_nullable_schema": is_nullable_schema,
+        "get_type_display": get_type_display,
     }
 
     env.globals.update(helpers)

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/md.py

@@ -49,7 +49,7 @@ def write_table_lines(
         if write_headers:
             # add separator line after headers
             yield write_row(
-                ["-" * column_len for column_len in columns_widths.values()],
+                ["-" * max(3, column_len) for column_len in columns_widths.values()],
                 columns_widths,
                 padding,
                 indent,

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/__init__.py

@@ -25,6 +25,19 @@ from openapidocs.mk.texts import EnglishTexts, Texts
 from openapidocs.mk.v3.examples import get_example_from_schema
 from openapidocs.utils.source import read_from_source
 
+_OAS31_KEYWORDS = frozenset(
+    {
+        "const",
+        "if",
+        "then",
+        "else",
+        "prefixItems",
+        "unevaluatedProperties",
+        "unevaluatedItems",
+        "$defs",
+    }
+)
+
 
 def _can_simplify_json(content_type) -> bool:
     return "json" in content_type or content_type == "text/plain"
@@ -106,11 +119,110 @@ class OpenAPIV3DocumentationHandler:
             custom_templates_path=templates_path,
         )
         self.doc = self.normalize_data(copy.deepcopy(doc))
+        self._warn_31_features_in_30_doc()
+        self._warn_30_features_in_31_doc()
 
     @property
     def source(self) -> str:
         return self._source
 
+    def _collect_31_features(self, obj: object, found: set) -> None:
+        """Recursively scans obj for OAS 3.1-specific features, collecting them in found."""
+        if not isinstance(obj, dict):
+            return
+
+        type_val = obj.get("type")
+        if isinstance(type_val, list):
+            found.add('type as list (e.g. ["string", "null"])')
+
+        for kw in _OAS31_KEYWORDS:
+            if kw in obj:
+                found.add(kw)
+
+        for kw in ("exclusiveMinimum", "exclusiveMaximum"):
+            val = obj.get(kw)
+            if (
+                val is not None
+                and isinstance(val, (int, float))
+                and not isinstance(val, bool)
+            ):
+                found.add(f"{kw} as number")
+
+        for value in obj.values():
+            if isinstance(value, dict):
+                self._collect_31_features(value, found)
+            elif isinstance(value, list):
+                for item in value:
+                    self._collect_31_features(item, found)
+
+    def _warn_31_features_in_30_doc(self) -> None:
+        """
+        Emits a warning if OAS 3.1-specific features are detected in a document
+        that declares an OAS 3.0.x version.
+        """
+        version = self.doc.get("openapi", "")
+        if not (isinstance(version, str) and version.startswith("3.0")):
+            return
+
+        found: set = set()
+
+        if "webhooks" in self.doc:
+            found.add("webhooks")
+
+        self._collect_31_features(self.doc, found)
+
+        if found:
+            feature_list = ", ".join(sorted(found))
+            warnings.warn(
+                f"OpenAPI document declares version {version!r} but uses "
+                f"OAS 3.1-specific features: {feature_list}. "
+                "Consider updating the `openapi` field to '3.1.0'.",
+                stacklevel=3,
+            )
+
+    def _collect_30_features(self, obj: object, found: set) -> None:
+        """Recursively scans obj for OAS 3.0-specific features, collecting them in found."""
+        if not isinstance(obj, dict):
+            return
+
+        # nullable: true is OAS 3.0 only — replaced by type: [..., "null"] in 3.1
+        if obj.get("nullable") is True:
+            found.add("nullable: true")
+
+        # boolean exclusiveMinimum/exclusiveMaximum are 3.0 semantics;
+        # in 3.1 they are numeric bounds
+        for kw in ("exclusiveMinimum", "exclusiveMaximum"):
+            if isinstance(obj.get(kw), bool):
+                found.add(f"{kw}: true/false (boolean)")
+
+        for value in obj.values():
+            if isinstance(value, dict):
+                self._collect_30_features(value, found)
+            elif isinstance(value, list):
+                for item in value:
+                    self._collect_30_features(item, found)
+
+    def _warn_30_features_in_31_doc(self) -> None:
+        """
+        Emits a warning if OAS 3.0-specific features are detected in a document
+        that declares an OAS 3.1.x version.
+        """
+        version = self.doc.get("openapi", "")
+        if not (isinstance(version, str) and version.startswith("3.1")):
+            return
+
+        found: set = set()
+        self._collect_30_features(self.doc, found)
+
+        if found:
+            feature_list = ", ".join(sorted(found))
+            warnings.warn(
+                f"OpenAPI document declares version {version!r} but uses "
+                f"OAS 3.0-specific features: {feature_list}. "
+                "These features are not valid in OAS 3.1 and may be ignored by tooling.",
+                stacklevel=3,
+            )
+
     def normalize_data(self, data):
         """
         Applies corrections to the OpenAPI specification, to simplify its handling.
@@ -125,6 +237,13 @@ class OpenAPIV3DocumentationHandler:
         $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"] = {}
 
@@ -156,18 +275,46 @@ class OpenAPIV3DocumentationHandler:
         Handles a dictionary containing a $ref property, resolving the reference if it
         is to a file. This is used to read specification files when they are split into
         multiple items.
+
+        Supports three forms:
+        - ``#/internal/ref``                    — internal ref, left as-is
+        - ``path/to/file.yaml``                 — entire external file
+        - ``path/to/file.yaml#/fragment/path``  — fragment within an external file
         """
         assert isinstance(obj, dict)
         if "$ref" in obj:
             reference = obj["$ref"]
             if isinstance(reference, str) and not reference.startswith("#/"):
-                referred_file = Path(os.path.abspath(source_path / reference))
+                # Split off an optional JSON Pointer fragment (#/...)
+                if "#" in reference:
+                    file_part, fragment = reference.split("#", 1)
+                else:
+                    file_part, fragment = reference, ""
+
+                referred_file = Path(os.path.abspath(source_path / file_part))
 
                 if referred_file.exists():
                     logger.debug("Handling $ref source: %s", reference)
                 else:
                     raise OpenAPIFileNotFoundError(reference, referred_file)
+
                 sub_fragment = read_from_source(str(referred_file))
+
+                if fragment:
+                    # Resolve the JSON Pointer (RFC 6901) into the loaded data.
+                    # Strip the leading '/' then split on '/'.
+                    keys = fragment.lstrip("/").split("/")
+                    for key in keys:
+                        if (
+                            not isinstance(sub_fragment, dict)
+                            or key not in sub_fragment
+                        ):
+                            raise OpenAPIDocumentationHandlerError(
+                                f"Cannot resolve fragment '{fragment}' in {referred_file}: "
+                                f"key '{key}' not found."
+                            )
+                        sub_fragment = sub_fragment[key]
+
                 return self._transform_data(sub_fragment, referred_file.parent)
             else:
                 return obj
@@ -179,7 +326,10 @@ class OpenAPIV3DocumentationHandler:
         """
         data = self.doc
         groups = defaultdict(list)
-        paths = data["paths"]
+        paths = data.get("paths")  # paths is optional in OAS 3.1
+
+        if not paths:
+            return groups
 
         for path, path_item in paths.items():
             if not isinstance(path_item, dict):
@@ -457,6 +607,19 @@ class OpenAPIV3DocumentationHandler:
 
         return results
 
+    def get_response_headers(self, response_definition: dict) -> dict:
+        """
+        Returns the headers of a response definition, resolving any $ref values
+        so that the template can access fields like schema and description directly.
+        """
+        headers = response_definition.get("headers")
+        if not headers:
+            return {}
+        return {
+            name: self._resolve_opt_ref(header_def)
+            for name, header_def in headers.items()
+        }
+
     def write(self) -> str:
         return self._writer.write(
             self.doc,

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/examples.py

@@ -35,6 +35,10 @@ class ScalarExampleHandler(SchemaExampleHandler):
     formats: Dict[str, Callable[[], Any]]
 
     def get_example(self, schema) -> str:
+        enum = schema.get("enum")
+        if isinstance(enum, list) and enum:
+            return enum[0]
+
         format = schema.get("format")
 
         if format and format in self.formats:
@@ -56,12 +60,6 @@ class StringExampleHandler(ScalarExampleHandler):
         "binary": lambda: "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ=",
     }
 
-    def get_example(self, schema) -> str:
-        enum = schema.get("enum")
-        if isinstance(enum, list):
-            return enum[0]
-        return super().get_example(schema)
-
 
 class IntegerExampleHandler(ScalarExampleHandler):
     type_name = "integer"
@@ -138,6 +136,10 @@ def get_example_from_schema(schema) -> Any:
     if "example" in schema:
         return schema["example"]
 
+    examples = schema.get("examples")
+    if isinstance(examples, list) and examples:
+        return examples[0]
+
     # does it have a type?
     handlers_types: List[Type[SchemaExampleHandler]] = list(
         get_subclasses(SchemaExampleHandler)
@@ -145,6 +147,11 @@ def get_example_from_schema(schema) -> Any:
 
     schema_type = schema.get("type")
 
+    # OAS 3.1: type can be a list (e.g. ["string", "null"]). Use the first non-null type.
+    if isinstance(schema_type, list):
+        non_null = [t for t in schema_type if t != "null"]
+        schema_type = non_null[0] if non_null else None
+
     if schema_type:
         handler_type = next(
             (_type for _type in handlers_types if _type.type_name == schema_type), None

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/components-responses.html

@@ -4,7 +4,7 @@
 {%- for name, definition in components.responses.items() %}
 
 ### {{name}}
-{% if definition.description %}{{definition.description | wordwrap(80)}}{% endif -%}
+{% if definition.description %}{{definition.description}}{% endif -%}
 
 {%- if definition.content -%}
 {% with content = handler.simplify_content(definition.content) -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/content-examples.html

@@ -3,6 +3,6 @@
 ```json
 {{handler.write_content_example(example, content_type) | safe}}
 ```
-{% if example.auto_generated %}_{{texts.auto_generated_example_note | wordwrap(80)}}_{% endif -%}
+{% if example.auto_generated %}_{{texts.auto_generated_example_note}}_{% endif -%}
 {% endif %}
 {% endfor %}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/external-docs.html

@@ -1,7 +1,7 @@
 ## {{texts.external_docs}}
 
 {% if externalDocs.description -%}
-{{externalDocs.description | wordwrap(80)}}
+{{externalDocs.description}}
 
 ---
 {% endif -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/info.html

@@ -1,7 +1,7 @@
 # {{info.title}} {{info.version}}
 
 {% if info.description -%}
-{{info.description | wordwrap(80)}}
+{{info.description}}
 
 ---
 {% endif -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/path-items.html

@@ -7,13 +7,13 @@
 
 ### {{http_method.upper()}} {{path | safe}}
 {% if "summary" in operation -%}
-{{operation.summary | wordwrap(80)}}
+{{operation.summary}}
 {%- endif -%}
 
 {%- if operation.description and operation.summary != operation.description %}
 
 **{{texts.description.title()}}**
-{{operation.description | wordwrap(80)}}
+{{operation.description}}
 
 {%- endif -%}
 

essentials_openapi-1.4.0/openapidocs/mk/v3/views_markdown/partial/request-parameters.html

@@ -0,0 +1,9 @@
+
+**{{texts.parameters}}**
+
+{% with rows = [[texts.parameter, texts.parameter_location, texts.type, texts.default, texts.nullable, texts.description]] %}
+{%- for param in parameters -%}
+{%- set _ = rows.append([param.name, param.in, get_type_display(read_dict(param, "schema", "type")), read_dict(param, "schema", "default", default=""), texts.get_yes_no(is_nullable_schema(read_dict(param, "schema") or {})), read_dict(param, "description", default="")]) -%}
+{%- endfor -%}
+{{ rows | table }}
+{%- endwith -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/request-responses.html

@@ -25,7 +25,7 @@ Refer to the common response description: [{{type_name}}](#{{type_name.lower()}}
 {%- if definition.headers %}
 
 {% with rows = [[texts.name, texts.description, texts.schema]] %}
-{%- for header_name, header_definition in definition.headers.items() -%}
+{%- for header_name, header_definition in handler.get_response_headers(definition).items() -%}
 {%- set _ = rows.append([header_name, header_definition.description, header_definition.schema.type]) -%}
 {%- endfor -%}
 {{ rows | table }}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/schema-repr.html

@@ -5,7 +5,7 @@
 {%- endif -%}
 
 {%- if schema.type -%}
-{%- with type_name = schema["type"], nullable = schema.get("nullable") -%}
+{%- with type_name = get_primary_type(schema["type"]), nullable = is_nullable_schema(schema) -%}
 {%- if type_name == "object" -%}
 {%- if schema.example -%}
 _{{texts.example}}: _`{{schema.example}}`
@@ -19,9 +19,7 @@ _{{texts.properties}}: _`{{", ".join(schema.properties.keys())}}`
 {%- if schema.format -%}
 ({{schema.format}})
 {%- endif -%}
-{%- if nullable -%}
-| null
-{%- endif -%}
+{%- if nullable %} | null{%- endif -%}
 {%- endif -%}
 {%- if type_name == "array" -%}
 {%- with schema = schema["items"] -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_markdown/partial/type.html

@@ -1,10 +1,10 @@
-{% if definition.type == "object" %}
+{% if get_primary_type(definition.type) == "object" %}
 {%- with props = handler.get_properties(definition) -%}
 {% if props %}
-| {{texts.name}} | {{texts.type}} |
-| -- | -- |
+| {{texts.name}} | {{texts.type}} | {{texts.description}} |
+| --- | --- | --- |
 {%- for name, schema in props %}
-| {{name}} | {% include "partial/schema-repr.html" %} |
+| {{name}} | {% include "partial/schema-repr.html" %} | {{schema.description}} |
 {%- endfor -%}
 {%- endif %}
 {%- endwith -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_mkdocs/partial/components-responses.html

@@ -5,7 +5,7 @@
 {% for name, definition in components.responses.items() %}
 
 ### {{name}}
-{% if definition.description %}{{definition.description | wordwrap(80)}}{% endif %}
+{% if definition.description %}{{definition.description}}{% endif %}
 
 {%- if definition.content %}
 {% with content = handler.simplify_content(definition.content) %}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_mkdocs/partial/external-docs.html

@@ -1,7 +1,7 @@
 ## {{texts.external_docs}}
 
 {% if externalDocs.description -%}
-{{externalDocs.description | wordwrap(80)}}
+{{externalDocs.description}}
 
 <hr />
 {%- endif -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_mkdocs/partial/info.html

@@ -1,7 +1,7 @@
 # {{info.title}} <span class="api-version">{{info.version}}</span>
 
 {% if info.description -%}
-{{info.description | wordwrap(80)}}
+{{info.description}}
 <hr />
 {%- endif -%}
 

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_mkdocs/partial/path-items.html

@@ -7,13 +7,13 @@
 
 ### <span class="http-{{http_method.lower()}}">{{http_method.upper()}}</span> {{path | route | safe}}
 {% if "summary" in operation -%}
-{{operation.summary | wordwrap(80)}}
+{{operation.summary}}
 {%- endif -%}
 
 {%- if operation.description and operation.summary != operation.description %}
 
 ??? note "{{texts.description.title()}}"
-    {{operation.description | wordwrap(76) | indent(4)}}
+    {{operation.description | indent(4)}}
 {% endif %}
 
 {%- with parameters = handler.get_parameters(operation) -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_mkdocs/partial/request-parameters.html

@@ -17,9 +17,9 @@
         <tr>
             <td class="parameter-name"><code>{{param.name}}</code></td>
             <td>{{param.in}}</td>
-            <td>{{read_dict(param, "schema", "type")}}</td>
+            <td>{{get_type_display(read_dict(param, "schema", "type"))}}</td>
             <td>{{read_dict(param, "schema", "default", default="")}}</td>
-            <td>{{texts.get_yes_no(read_dict(param, "schema", "nullable", default=False))}}</td>
+            <td>{{texts.get_yes_no(is_nullable_schema(read_dict(param, "schema") or {}))}}</td>
             <td>{{read_dict(param, "description", default="")}}</td>
         </tr>
         {%- endfor %}

essentials_openapi-1.4.0/openapidocs/mk/v3/views_mkdocs/partial/request-responses.html

@@ -0,0 +1,42 @@
+<p class="responses-title"><strong>{{texts.responses}}</strong></p>
+
+{% for code, definition in operation.responses.items() %}
+=== "{% if code == "default" %}{{texts.other_responses}}{% else %}{{code}}{% with phrase = get_http_status_phrase(code) %}{% if phrase %} {{ phrase }}{% endif %}{% endwith %}{% endif %}"
+    {%- if is_reference(definition) -%}
+    {%- with type_name = definition["$ref"].replace("#/components/responses/", "") %}
+    <div class="common-response"><p>Refer to the common response description: <a href="#{{type_name.lower() | link}}" class="ref-link">{{type_name}}</a>.</p></div>
+    {%- endwith -%}
+    {%- endif -%}
+    {%- if definition.content %}
+    {%- with content = handler.simplify_content(definition.content) %}
+    {% for content_type, definition in content.items() %}
+    === "{{content_type}}"
+        {% for example in handler.get_content_examples(definition) %}
+        {% if example.value %}
+        ```json
+        {{handler.write_content_example(example, content_type) | indent(8) | safe}}
+        ```
+        {% if example.auto_generated %}<span class="small-note">⚠️</span>&nbsp;<em class="small-note warning">{{texts.auto_generated_example_note}}</em>{% endif -%}
+        {% endif %}
+        {% endfor %}
+        {% if "alt_types" in definition %}<em class="small-note alt-types">{{texts.other_possible_types}}: {{definition.alt_types | join(", ")}}</em>{% endif %}
+
+        ??? hint "{{texts.schema_of_the_response_body}}"
+            ```json
+            {{handler.write_content_schema(definition) | indent(12) | safe}}
+            ```
+    {% endfor %}
+    {% endwith -%}
+    {% endif -%}
+    {%- if definition.headers %}
+
+    **{{texts.response_headers}}**
+
+    | {{texts.name}} | {{texts.description}} | {{texts.schema}} |
+    | --- | --- | --- |
+    {%- for header_name, header_definition in handler.get_response_headers(definition).items() %}
+    | `{{header_name}}` | {{header_definition.description or ""}} | {%- with schema = header_definition.schema %}{%- include "partial/schema-repr.html" -%}{%- endwith %} |
+    {%- endfor %}
+
+    {% endif -%}
+{%- endfor -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_mkdocs/partial/schema-repr.html

@@ -5,7 +5,7 @@
 {%- endif -%}
 
 {%- if schema.type -%}
-{%- with type_name = schema["type"], nullable = schema.get("nullable") -%}
+{%- with type_name = get_primary_type(schema["type"]), nullable = is_nullable_schema(schema) -%}
 {%- if type_name == "object" -%}
 {%- if schema.example -%}
 <em>{{texts.example}}: </em><code>{{schema.example}}</code>
@@ -19,9 +19,7 @@
 {%- if schema.format -%}
 (<span class="{{schema.format}}-format format">{{schema.format}}</span>)
 {%- endif -%}
-{%- if nullable -%}
-&#124; <span class="null-type">null</span>
-{%- endif -%}
+{%- if nullable %} &#124; <span class="null-type">null</span>{%- endif -%}
 {%- endif -%}
 {%- if type_name == "array" -%}
 {%- with schema = schema["items"] -%}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_mkdocs/partial/type.html

@@ -1,4 +1,4 @@
-{% if definition.type == "object" %}
+{% if get_primary_type(definition.type) == "object" %}
 {%- with props = handler.get_properties(definition) -%}
 {% if props %}
 <table>
@@ -6,6 +6,7 @@
         <tr>
             <th>{{texts.name}}</th>
             <th>{{texts.type}}</th>
+            <th>{{texts.description}}</th>
         </tr>
     </thead>
     <tbody>
@@ -13,6 +14,7 @@
         <tr>
             <td><code>{{name}}</code></td>
             <td>{% include "partial/schema-repr.html" %}</td>
+            <td>{{schema.description}}</td>
         </tr>
         {%- endfor %}
     </tbody>

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_plantuml_api/partial/schema-repr.html

@@ -5,7 +5,7 @@
 {%- endif -%}
 
 {%- if schema.type -%}
-{%- with type_name = schema["type"], nullable = schema.get("nullable") -%}
+{%- with type_name = get_primary_type(schema["type"]), nullable = is_nullable_schema(schema) -%}
 {# Scalar types #}
 {%- if type_name in scalar_types -%}
 {{type_name}}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/mk/v3/views_plantuml_schemas/partial/schema-repr.html

@@ -5,7 +5,7 @@
 {%- endif -%}
 
 {%- if schema.type -%}
-{%- with type_name = schema["type"], nullable = schema.get("nullable") -%}
+{%- with type_name = get_primary_type(schema["type"]), nullable = is_nullable_schema(schema) -%}
 {# Scalar types #}
 {%- if type_name in scalar_types -%}
 {{type_name}}

{essentials_openapi-1.3.0 → essentials_openapi-1.4.0}/openapidocs/v3.py

@@ -350,8 +350,30 @@ class Schema(OpenAPIElement):
             A list of schemas where at least one must apply.
         one_of (list["Schema" | "Reference"] | None):
             A list of schemas where exactly one must apply.
-        not_ (list["Schema" | "Reference"] | None):
+        not_ (None | "Schema" | "Reference"):
             A schema that must not apply.
+        if_ (None | "Schema" | "Reference"):
+            If-then-else conditional schema (JSON Schema / OAS 3.1).
+        then_ (None | "Schema" | "Reference"):
+            Schema applied when if_ validates successfully.
+        else_ (None | "Schema" | "Reference"):
+            Schema applied when if_ fails to validate.
+        exclusive_maximum (float | None):
+            OAS 3.1 / JSON Schema: the exclusive upper bound for numeric values.
+        exclusive_minimum (float | None):
+            OAS 3.1 / JSON Schema: the exclusive lower bound for numeric values.
+        multiple_of (float | None):
+            The value must be a multiple of this number.
+        const (Any | None):
+            OAS 3.1 / JSON Schema: the value must be exactly this value.
+        prefix_items (list["Schema" | "Reference"] | None):
+            OAS 3.1 / JSON Schema: schemas for tuple validation of array items.
+        unevaluated_properties (None | bool | "Schema" | "Reference"):
+            OAS 3.1 / JSON Schema: controls handling of unevaluated properties.
+        unevaluated_items (None | bool | "Schema" | "Reference"):
+            OAS 3.1 / JSON Schema: controls handling of unevaluated array items.
+        defs (dict[str, "Schema" | "Reference"] | None):
+            OAS 3.1 / JSON Schema: locally-scoped schema definitions ($defs).
     """
 
     type: None | str | ValueType | list[None | str | ValueType] = None
@@ -376,15 +398,26 @@ class Schema(OpenAPIElement):
     unique_items: bool | None = None
     maximum: float | None = None
     minimum: float | None = None
+    exclusive_maximum: float | None = None
+    exclusive_minimum: float | None = None
+    multiple_of: float | None = None
     nullable: bool | None = None
     xml: XML | None = None
     items: "None | Schema | Reference" = None
-    enum: list[str] | None = None
+    prefix_items: list["Schema | Reference"] | None = None
+    enum: list[Any] | None = None
+    const: Any | None = None
     discriminator: Discriminator | None = None
     all_of: list["Schema | Reference"] | None = None
     any_of: list["Schema | Reference"] | None = None
     one_of: list["Schema | Reference"] | None = None
-    not_: list["Schema | Reference"] | None = None
+    not_: "None | Schema | Reference" = None
+    if_: "None | Schema | Reference" = None
+    then_: "None | Schema | Reference" = None
+    else_: "None | Schema | Reference" = None
+    unevaluated_properties: "None | bool | Schema | Reference" = None
+    unevaluated_items: "None | bool | Schema | Reference" = None
+    defs: dict[str, "Schema | Reference"] | None = None
 
 
 @dataclass
@@ -924,8 +957,8 @@ class OpenAPI(OpenAPIRoot):
     Attributes:
         openapi (str): The semantic version number of the OpenAPI Specification version.
         info (Info | None): Metadata about the API.
-        json_schema_dialect (str): The default value for the $schema keyword within Schema Objects contained
-                                  within this OAS document.
+        json_schema_dialect (str | None): The default value for the $schema keyword within Schema Objects contained
+                                  within this OAS document. Optional; if omitted, the dialect is not declared.
         paths (dict[str, PathItem] | None): The available paths and operations for the API.
         servers (list[Server] | None): An array of Server Objects that provide connectivity information
                                         to a target server.
@@ -938,7 +971,7 @@ class OpenAPI(OpenAPIRoot):
 
     openapi: str = "3.1.0"
     info: Info | None = None
-    json_schema_dialect: str = "https://json-schema.org/draft/2020-12/schema"
+    json_schema_dialect: str | None = None
     paths: dict[str, PathItem] | None = None
     servers: list[Server] | None = None
     components: Components | None = None

essentials_openapi-1.3.0/openapidocs/mk/v3/views_markdown/partial/request-parameters.html

@@ -1,9 +0,0 @@
-
-**{{texts.parameters}}**
-
-{% with rows = [[texts.parameter, texts.parameter_location, texts.type, texts.default, texts.nullable, texts.description]] %}
-{%- for param in parameters -%}
-{%- set _ = rows.append([param.name, param.in, read_dict(param, "schema", "type"), read_dict(param, "schema", "default", default=""), texts.get_yes_no(read_dict(param, "schema", "nullable", default=False)), read_dict(param, "description", default="")]) -%}
-{%- endfor -%}
-{{ rows | table }}
-{%- endwith -%}

essentials_openapi-1.3.0/openapidocs/mk/v3/views_mkdocs/partial/request-responses.html

@@ -1,63 +0,0 @@
-{% for code, definition in operation.responses.items() %}
-
-<p class="response-title">
-    {% if code == "default" -%}
-    <strong>{{texts.other_responses}}</strong>
-    {%- else -%}
-    <strong>Response <span class="response-code code-{{code}}">{{code}}</span>
-    {%- with phrase = get_http_status_phrase(code) -%}
-    {%- if phrase -%}
-    &nbsp;<span class="status-phrase">{{ phrase }}</span>
-    {%- endif -%}
-    {%- endwith -%}
-    </strong>
-    {%- endif %}
-</p>
-{%- if is_reference(definition) -%}
-{%- with type_name = definition["$ref"].replace("#/components/responses/", "") %}
-<div class="common-response"><p>Refer to the common response description: <a href="#{{type_name.lower() | link}}" class="ref-link">{{type_name}}</a>.</p></div>
-{%- endwith -%}
-{%- endif -%}
-{%- if definition.content %}
-{%- with content = handler.simplify_content(definition.content) %}
-{% for content_type, definition in content.items() %}
-=== "{{content_type}}"
-    {% include "partial/content-examples.html" %}
-    {% if "alt_types" in definition %}<em class="small-note alt-types">{{texts.other_possible_types}}: {{definition.alt_types | join(", ")}}</em>{% endif %}
-
-    ??? hint "{{texts.schema_of_the_response_body}}"
-        ```json
-        {{handler.write_content_schema(definition) | indent(8) | safe}}
-        ```
-{% endfor %}
-{% endwith -%}
-{% endif -%}
-{%- if definition.headers %}
-<div class="response-section">
-    <p class="response-headers sub-section-title">{{texts.response_headers}}</p>
-
-    <table>
-        <thead>
-            <tr>
-                <th>{{texts.name}}</th>
-                <th>{{texts.description}}</th>
-                <th>{{texts.schema}}</th>
-            </tr>
-        </thead>
-        <tbody>
-            {%- for header_name, header_definition in definition.headers.items() %}
-            <tr>
-                <td><code>{{header_name}}</code></td>
-                <td>{{header_definition.description}}</td>
-                <td>
-                    {%- with schema = header_definition.schema %}
-                    {%- include "partial/schema-repr.html" -%}
-                    {% endwith -%}
-                </td>
-            </tr>
-            {%- endfor %}
-        </tbody>
-    </table>
-</div>
-{% endif -%}
-{%- endfor -%}