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

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

@@ -5,6 +5,36 @@ 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
 
 - Added support for using the current working directory (CWD) as an option when

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: essentials-openapi
-Version: 1.2.1
+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
@@ -11,12 +11,12 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
 Requires-Dist: essentials>=1.1.5
 Requires-Dist: markupsafe>=3.0.0
 Requires-Dist: pyyaml>=6
@@ -102,6 +102,34 @@ oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_API"
 
 _Example of PlantUML diagram generated from path items._
 
+#### Using custom templates
+
+You can override the default templates by providing a custom templates directory:
+
+```bash
+oad gen-docs -s source-openapi.json -d output.md -T ./my-templates/
+```
+
+The custom templates directory should contain template files with the same names as the built-in templates. Any template file found in the custom directory will override the corresponding default template, while non-overridden templates will use the defaults. This follows the same pattern as [MkDocs template customization](https://www.mkdocs.org/user-guide/customizing-your-theme/#overriding-template-blocks).
+
+**Important:** The custom templates directory must match the output style being rendered. Each style (MKDOCS, MARKDOWN, PLANTUML_SCHEMAS, PLANTUML_API) has its own template structure. You need to provide templates appropriate for the `--style` parameter you're using.
+
+**Template structure:**
+- `layout.html` - Main layout template
+- `partial/` - Directory containing reusable template components
+
+**Example custom template directory structure:**
+```
+my-templates/
+├── layout.html          # Overrides main layout
+└── partial/
+    ├── info.html       # Overrides info section
+    └── path-items.html # Overrides path items section
+```
+
+All templates use [Jinja2](https://jinja.palletsprojects.com/) syntax and have access to the same filters, functions, and context variables as the built-in templates.
+
+
 ### Goals
 
 * Provide an API to generate OpenAPI Documentation files.

{essentials_openapi-1.2.1 → essentials_openapi-1.4.0}/README.md

@@ -73,6 +73,34 @@ oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_API"
 
 _Example of PlantUML diagram generated from path items._
 
+#### Using custom templates
+
+You can override the default templates by providing a custom templates directory:
+
+```bash
+oad gen-docs -s source-openapi.json -d output.md -T ./my-templates/
+```
+
+The custom templates directory should contain template files with the same names as the built-in templates. Any template file found in the custom directory will override the corresponding default template, while non-overridden templates will use the defaults. This follows the same pattern as [MkDocs template customization](https://www.mkdocs.org/user-guide/customizing-your-theme/#overriding-template-blocks).
+
+**Important:** The custom templates directory must match the output style being rendered. Each style (MKDOCS, MARKDOWN, PLANTUML_SCHEMAS, PLANTUML_API) has its own template structure. You need to provide templates appropriate for the `--style` parameter you're using.
+
+**Template structure:**
+- `layout.html` - Main layout template
+- `partial/` - Directory containing reusable template components
+
+**Example custom template directory structure:**
+```
+my-templates/
+├── layout.html          # Overrides main layout
+└── partial/
+    ├── info.html       # Overrides info section
+    └── path-items.html # Overrides path items section
+```
+
+All templates use [Jinja2](https://jinja.palletsprojects.com/) syntax and have access to the same filters, functions, and context variables as the built-in templates.
+
+
 ### Goals
 
 * Provide an API to generate OpenAPI Documentation files.

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

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

{essentials_openapi-1.2.1 → essentials_openapi-1.4.0}/openapidocs/commands/docs.py

@@ -31,7 +31,20 @@ from openapidocs.mk.jinja import OutputStyle
     default="MKDOCS",
     show_default=True,
 )
-def generate_documents_command(source: str, destination: str, style: Union[int, str]):
+@click.option(
+    "-T",
+    "--templates",
+    help=(
+        "Path to a custom templates directory. "
+        "Templates in this directory will override default templates with matching names. "
+        "Unspecified templates will use defaults."
+    ),
+    required=False,
+    default=None,
+)
+def generate_documents_command(
+    source: str, destination: str, style: Union[int, str], templates: Union[str, None]
+):
     """
     Generates other kinds of documents from source OpenAPI Documentation files.
 
@@ -48,7 +61,7 @@ def generate_documents_command(source: str, destination: str, style: Union[int,
     https://github.com/Neoteroi/essentials-openapi
     """
     try:
-        generate_document(source, destination, style)
+        generate_document(source, destination, style, templates)
     except KeyboardInterrupt:  # pragma: nocover
         logger.info("User interrupted")
         exit(1)

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

@@ -1,10 +1,10 @@
 import base64
 import copy
 from abc import ABC, abstractmethod
-from dataclasses import asdict, fields, is_dataclass
+from dataclasses import asdict, dataclass, fields, is_dataclass
 from datetime import date, datetime, time
 from enum import Enum
-from typing import Any, List, Tuple
+from typing import Any, Callable, Iterable, cast
 from uuid import UUID
 
 import yaml
@@ -18,10 +18,12 @@ class Format(Enum):
     JSON = "JSON"
 
 
+@dataclass
 class OpenAPIElement:
     """Base class for all OpenAPI Elements"""
 
 
+@dataclass
 class OpenAPIRoot(OpenAPIElement):
     """Base class for a root OpenAPI Documentation"""
 
@@ -67,8 +69,8 @@ def normalize_key(key: Any) -> str:
     return "".join([first.lower(), *map(str.title, others)])
 
 
-def normalize_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
-    data = {}
+def normalize_dict_factory(items: list[tuple[Any, Any]]) -> dict[str, Any]:
+    data: dict[str, Any] = {}
     for key, value in items:
         if value is None:
             continue
@@ -80,6 +82,10 @@ def normalize_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
             data["$ref"] = value
             continue
 
+        if key == "defs":
+            data["$defs"] = value
+            continue
+
         for handler in TYPES_HANDLERS:
             value = handler.normalize(value)
 
@@ -87,8 +93,8 @@ def normalize_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
     return data
 
 
-def regular_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
-    data = {}
+def regular_dict_factory(items: list[tuple[Any, Any]]) -> dict[Any, Any]:
+    data: dict[Any, Any] = {}
     for key, value in items:
         for handler in TYPES_HANDLERS:
             value = handler.normalize(value)
@@ -100,11 +106,11 @@ def regular_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
 # replicates the asdict method from dataclasses module, to support
 # bypassing "asdict" on child properties when they implement a `to_obj`
 # method: some entities require a specific shape when represented
-def _asdict_inner(obj, dict_factory):
+def _asdict_inner(obj: Any, dict_factory: Callable[[Any], Any]) -> Any:
     if hasattr(obj, "to_obj"):
         return obj.to_obj()
     if isinstance(obj, OpenAPIElement):
-        result = []
+        result: list[tuple[str, Any]] = []
         for f in fields(obj):
             value = _asdict_inner(getattr(obj, f.name), dict_factory)
             result.append((f.name, value))
@@ -115,20 +121,24 @@ def _asdict_inner(obj, dict_factory):
     if hasattr(obj, "dict") and callable(obj.dict):
         # For Pydantic 1
         return obj.dict()
-    if is_dataclass(obj):
+    if is_dataclass(obj) and not isinstance(obj, type):
         return asdict(obj, dict_factory=regular_dict_factory)
     elif isinstance(obj, (list, tuple)):
+        obj = cast(Iterable[Any], obj)
         return type(obj)(_asdict_inner(v, dict_factory) for v in obj)
     elif isinstance(obj, dict):
+        obj = cast(dict[Any, Any], obj)
         return type(obj)(
             (_asdict_inner(k, dict_factory), _asdict_inner(v, dict_factory))
             for k, v in obj.items()
         )
     else:
+        for handler in TYPES_HANDLERS:
+            obj = handler.normalize(obj)
         return copy.deepcopy(obj)
 
 
-def normalize_dict(obj):
+def normalize_dict(obj: Any) -> Any:
     if hasattr(obj, "dict") and callable(obj.dict):
         return obj.dict()
     if hasattr(obj, "to_obj"):

{essentials_openapi-1.2.1 → essentials_openapi-1.4.0}/openapidocs/logs.py

@@ -1,5 +1,4 @@
 import logging
-import logging.handlers
 
 from rich.logging import RichHandler
 

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

@@ -5,6 +5,7 @@ from source OAD files.
 """
 
 from abc import ABC, abstractmethod
+from typing import Any, cast
 
 
 class DocumentsWriter(ABC):
@@ -14,13 +15,13 @@ class DocumentsWriter(ABC):
     """
 
     @abstractmethod
-    def write(self, data, **kwargs) -> str:
+    def write(self, data: object, **kwargs: dict[str, Any]) -> str:
         """
         Writes markdown.
         """
 
 
-def is_reference(data) -> bool:
+def is_reference(data: object) -> bool:
     """
     Returns a value indicating whether the given dictionary represents
     a reference.
@@ -32,31 +33,47 @@ def is_reference(data) -> bool:
     return "$ref" in data
 
 
-def is_object_schema(data) -> bool:
+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
-    return data.get("type") == "object" and isinstance(data.get("properties"), dict)
+    data = cast(dict[str, object], data)
+    return _type_matches(data.get("type"), "object") and isinstance(
+        data.get("properties"), dict
+    )
 
 
-def is_array_schema(data) -> bool:
+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
-    return data.get("type") == "array" and isinstance(data.get("items"), dict)
+    data = cast(dict[str, object], data)
+    return _type_matches(data.get("type"), "array") and isinstance(
+        data.get("items"), dict
+    )
 
 
-def get_ref_type_name(reference) -> str:
+def get_ref_type_name(reference: dict[str, str] | str) -> str:
     """
     Returns the type name of a reference.
 

{essentials_openapi-1.2.1 → essentials_openapi-1.4.0}/openapidocs/mk/contents.py

@@ -1,27 +1,29 @@
 """
 This module contains classes to generate representations of content types by mime type.
 """
+
 import os
 from abc import ABC, abstractmethod
 from datetime import datetime
 from json import JSONEncoder
+from typing import Any, Mapping, Sequence
 from urllib.parse import urlencode
 
 from essentials.json import FriendlyEncoder, dumps
 
 
 class OADJSONEncoder(JSONEncoder):
-    def default(self, obj):
+    def default(self, o: object) -> Any:
         try:
-            return JSONEncoder.default(self, obj)
+            return JSONEncoder.default(self, o)
         except TypeError:
-            if isinstance(obj, datetime):
+            if isinstance(o, datetime):
                 datetime_format = os.environ.get("OPENAPI_DATETIME_FORMAT")
                 if datetime_format:
-                    return obj.strftime(datetime_format)
+                    return o.strftime(datetime_format)
                 else:
-                    return obj.isoformat()
-            return FriendlyEncoder.default(self, obj)  # type: ignore
+                    return o.isoformat()
+            return FriendlyEncoder.default(self, o)  # type: ignore
 
 
 class ContentWriter(ABC):
@@ -37,7 +39,7 @@ class ContentWriter(ABC):
         """
 
     @abstractmethod
-    def write(self, value) -> str:
+    def write(self, value: Any) -> str:
         """
         Writes markdown to represent a value in a certain type of content.
         """
@@ -47,7 +49,7 @@ class JSONContentWriter(ContentWriter):
     def handle_content_type(self, content_type: str) -> bool:
         return "json" in content_type.lower()
 
-    def write(self, value) -> str:
+    def write(self, value: object) -> str:
         return dumps(value, indent=4, cls=OADJSONEncoder)
 
 
@@ -56,5 +58,5 @@ class FormContentWriter(ContentWriter):
         # multipart/form-data. Otherwise, use application/x-www-form-urlencoded.
         return "x-www-form-urlencoded" == content_type.lower()
 
-    def write(self, value) -> str:
+    def write(self, value: Mapping[Any, Any] | Sequence[tuple[Any, Any]]) -> str:
         return urlencode(value)

{essentials_openapi-1.2.1 → essentials_openapi-1.4.0}/openapidocs/mk/generate.py

@@ -1,15 +1,22 @@
-from typing import Union
+from typing import Optional
 
 from openapidocs.mk.v3 import OpenAPIV3DocumentationHandler
 from openapidocs.utils.source import read_from_source
 
 
-def generate_document(source: str, destination: str, style: Union[int, str]):
+def generate_document(
+    source: str,
+    destination: str,
+    style: int | str,
+    templates_path: Optional[str] = None,
+):
     # Note: if support for more kinds of OAD versions will be added, handle a version
     # parameter in this function
 
     data = read_from_source(source)
-    handler = OpenAPIV3DocumentationHandler(data, style=style, source=source)
+    handler = OpenAPIV3DocumentationHandler(
+        data, style=style, source=source, templates_path=templates_path
+    )
 
     html = handler.write()
 

essentials_openapi-1.4.0/openapidocs/mk/jinja.py

@@ -0,0 +1,197 @@
+"""
+This module provides a Jinja2 environment.
+"""
+
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from jinja2 import (
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    Template,
+    select_autoescape,
+)
+
+from . import get_http_status_phrase, highlight_params, read_dict, sort_dict
+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}
+    )
+
+
+def configure_functions(env: Environment):
+    helpers = {
+        "read_dict": read_dict,
+        "sort_dict": sort_dict,
+        "is_reference": is_reference,
+        "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)
+
+
+class OutputStyle(Enum):
+    """
+    Output style.
+    """
+
+    MKDOCS = 1
+    """Markdown for MkDocs and PyMdown extensions"""
+
+    MARKDOWN = 2
+    """Basic Markdown"""
+
+    PLANTUML_SCHEMAS = 100
+    """PlantUML class diagram for components schemas."""
+
+    PLANTUML_API = 101
+    """PlantUML diagram of the API with request and response bodies."""
+
+
+class PackageLoadingError(ValueError):
+    def __init__(
+        self, style: OutputStyle, templates_folder: str
+    ) -> None:  # pragma: no cover
+        super().__init__(
+            f"Failed to read the templates for the output style {style.name}. "
+            f"Tried to read templates from the folder: {__name__}.{templates_folder}. "
+            "This is most probably an issue in `essentials-openapi`."
+        )
+        self.desired_style = style
+        self.attempted_folder = templates_folder
+
+
+def get_environment(
+    package_name: str,
+    views_style: OutputStyle = OutputStyle.MKDOCS,
+    custom_templates_path: Optional[str] = None,
+) -> Environment:
+    templates_folder = f"views_{views_style.name}".lower()
+
+    loaders = []
+
+    # If custom templates path is provided, validate and add FileSystemLoader first
+    if custom_templates_path:
+        custom_path = Path(custom_templates_path)
+        if not custom_path.exists():
+            raise ValueError(
+                f"Custom templates path does not exist: {custom_templates_path}"
+            )
+        if not custom_path.is_dir():
+            raise ValueError(
+                f"Custom templates path is not a directory: {custom_templates_path}"
+            )
+        loaders.append(FileSystemLoader(str(custom_path)))
+
+    # Always add the package loader as fallback
+    try:
+        loaders.append(PackageLoader(package_name, templates_folder))
+    except ValueError as package_loading_error:  # pragma: no cover
+        if not custom_templates_path:
+            raise PackageLoadingError(
+                views_style, templates_folder
+            ) from package_loading_error
+
+    loader = ChoiceLoader(loaders)
+
+    env = Environment(
+        loader=loader,
+        autoescape=select_autoescape(["html", "xml"])
+        if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
+        else False,
+        auto_reload=True,
+        enable_async=False,
+    )
+    configure_filters(env)
+    configure_functions(env)
+
+    return env
+
+
+class Jinja2DocumentsWriter(DocumentsWriter):
+    """
+    This class uses Jinja2 templating engine to generate other kinds of text output from
+    source OpenAPI Documentation data.
+    """
+
+    def __init__(
+        self,
+        package_name: str,
+        views_style: OutputStyle = OutputStyle.MKDOCS,
+        custom_templates_path: Optional[str] = None,
+    ) -> None:
+        self._env = get_environment(package_name, views_style, custom_templates_path)
+
+    @property
+    def env(self) -> Environment:
+        return self._env
+
+    def get_template(self) -> Template:
+        return self.env.get_template("layout.html")
+
+    def write(self, data, **kwargs) -> str:
+        template = self.get_template()
+        return template.render(data, **kwargs)

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

@@ -2,12 +2,13 @@
 This module provides common functions to handle Markdown.
 These functions apply to any kind of Markdown work.
 """
-from typing import Dict, Iterable
+
+from typing import Iterable
 
 
 def write_row(
     row: Iterable[str],
-    columns_widths: Dict[int, int],
+    columns_widths: dict[int, int],
     padding: int = 1,
     indent: int = 0,
 ) -> str:
@@ -48,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,