essentials-openapi 1.1.0__tar.gz → 1.2.0__tar.gz

{essentials_openapi-1.1.0 → essentials_openapi-1.2.0}/.gitignore

@@ -9,3 +9,4 @@ _test_files/
 dist/
 venv312/
 .local
+v3_debug_*

{essentials_openapi-1.1.0 → essentials_openapi-1.2.0}/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.2.0] - 2025-04-27
+
+- Update objects to the OpenAPI Specification v3.1, by @tyzhnenko.
+- Add docstrings to all `v3` classes.
+- Upgrade the `v3.OpenAPI` class from OpenAPI version `3.0.3` to `3.1.0`.
+
+## [1.1.1] - 2025-03-20
+
+- Fix bug in `MARKDOWN` view for `servers` (displaying twice the `description`
+  instead of `description` and `url`).
+- Fix bug happening when a `path item` includes properties that are not of kind
+  `operation item` (https://github.com/Neoteroi/mkdocs-plugins/issues/5).
+- Add support for handling `parameters` defined on `path items` (common
+  parameters for all operation under a certain path).
+  Refer to the [`Path Item` specification](https://swagger.io/specification/#path-item-object).
+- Fix bug happening when a parameter has a non-str `name` property.
+- Add Python 3.13 to the build matrix.
+
 ## [1.1.0] - 2025-01-18
 
 - Add additionalProperties to Schema object, by @tyzhnenko.

{essentials_openapi-1.1.0 → essentials_openapi-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: essentials-openapi
-Version: 1.1.0
+Version: 1.2.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.1.0 → essentials_openapi-1.2.0}/openapidocs/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 VERSION = __version__

{essentials_openapi-1.1.0 → essentials_openapi-1.2.0}/openapidocs/mk/v3/__init__.py

@@ -178,6 +178,8 @@ class OpenAPIV3DocumentationHandler:
         paths = data["paths"]
 
         for path, path_item in paths.items():
+            if not isinstance(path_item, dict):
+                continue
             tag = self.get_tag(path_item) or ""
 
             for operation in path_item.values():
@@ -186,11 +188,32 @@ class OpenAPIV3DocumentationHandler:
                     operation["requestBody"] = self._resolve_opt_ref(
                         operation["requestBody"]
                     )
-
-            groups[tag].append((path, path_item))
+            groups[tag].append((path, self._keep_operations(path_item)))
 
         return groups
 
+    def _keep_operations(self, path_item):
+        # discard dictionary keys that are not of dict type
+
+        # if the path item defines common parameters, merge them into each operation:
+        # https://swagger.io/specification/#path-item-object
+        common_parameters = path_item.get("parameters", [])
+        # Note: we don't need to resolve $ref here, because they are resolved in
+        # get_parameters
+
+        return {
+            key: self._merge_common_parameters(value, common_parameters)
+            for key, value in path_item.items()
+            if isinstance(value, dict)
+        }
+
+    def _merge_common_parameters(self, operation, common_parameters):
+        if not common_parameters:
+            return operation
+        data = copy.deepcopy(operation)
+        data["parameters"] = common_parameters + data.get("parameters", [])
+        return data
+
     def get_schemas(self):
         schemas = read_dict(self.doc, "components", "schemas")
 
@@ -215,8 +238,12 @@ class OpenAPIV3DocumentationHandler:
         """
         single_tag: Optional[str] = None
 
-        for operation in path_item.values():
-            tags = operation.get("tags")
+        for prop in path_item.values():
+            if not isinstance(prop, dict):
+                # This property is not an operation; in this context we ignore it.
+                # See Path Item Object here: https://swagger.io/specification/
+                continue
+            tags = prop.get("tags")
 
             if not tags:
                 continue
@@ -383,6 +410,11 @@ class OpenAPIV3DocumentationHandler:
             return self.resolve_reference(obj)
         return obj
 
+    def _lower(self, obj):
+        if isinstance(obj, str):
+            return obj.lower()
+        return str(obj)
+
     def get_parameters(self, operation) -> List[dict]:
         """
         Returns a list of objects describing the input parameters for a given operation.
@@ -397,7 +429,7 @@ class OpenAPIV3DocumentationHandler:
             param
             for param in sorted(
                 parameters,
-                key=lambda x: x["name"].lower() if (x and "name" in x) else "",
+                key=lambda x: self._lower(x["name"]) if (x and "name" in x) else "",
             )
             if param
         ]

{essentials_openapi-1.1.0 → essentials_openapi-1.2.0}/openapidocs/mk/v3/views_markdown/partial/servers.html

@@ -3,7 +3,7 @@
 
 {% with rows = [[texts.description, texts.url]] %}
 {%- for server in servers -%}
-{%- set _ = rows.append([server.description, server.description]) -%}
+{%- set _ = rows.append([server.description, server.url]) -%}
 {%- endfor -%}
 {{ rows | table }}
 {%- endwith -%}