v1.0.6 🐌

CHANGELOG.md

@@ -5,10 +5,17 @@ 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
+## [1.0.6] - 2023-03-19 :snail:
 - Fixes a bug happening when trying to serialize examples in JSON, when they
-  contain datetimes and are provided in YAML.
+  contain datetimes and are provided in YAML;
   ([bug report](https://github.com/Neoteroi/mkdocs-plugins/issues/35)).
+- Fixes a bug related to missing resolution of references for `requestBody`;
+  ([bug report](https://github.com/Neoteroi/essentials-openapi/issues/21)).
+- Fixes support for code fences (disables by default `autoescape`, since the
+  source of OpenAPI Specification files is supposed to be trusted anyway.
+  Those who still wants to have `autoescape` enabled with `Jinja` can do so
+  setting an environment variable: `SELECT_AUTOESCAPE=1`.
+  ([bug report](https://github.com/Neoteroi/essentials-openapi/issues/24)).
 
 ## [1.0.5] - 2022-12-22 :santa:
 - Fixes [#22](https://github.com/Neoteroi/essentials-openapi/issues/22)

openapidocs/mk/jinja.py

@@ -1,6 +1,7 @@
 """
-This module provides a Jinja2 environment to
+This module provides a Jinja2 environment.
 """
+import os
 from enum import Enum
 
 from jinja2 import Environment, PackageLoader, Template, select_autoescape
@@ -74,7 +75,9 @@ def get_environment(
     else:
         env = Environment(
             loader=loader,
-            autoescape=select_autoescape(["html", "xml"]),
+            autoescape=select_autoescape(["html", "xml"])
+            if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
+            else False,
             auto_reload=True,
             enable_async=False,
         )

openapidocs/mk/v3/__init__.py

@@ -179,6 +179,14 @@ def get_operations(self):
 
         for path, path_item in paths.items():
             tag = self.get_tag(path_item) or ""
+
+            for operation in path_item.values():
+                # need to resolve possible references for requestBody
+                if "requestBody" in operation:
+                    operation["requestBody"] = self._resolve_opt_ref(
+                        operation["requestBody"]
+                    )
+
             groups[tag].append((path, path_item))
 
         return groups

openapidocs/mk/v3/views_markdown/partial/path-items.html

@@ -28,7 +28,9 @@
 {% include "partial/request-body.html" %}
 {%- endif %}
 
+{%- if operation.responses %}
 {%- include "partial/request-responses.html" %}
+{%- endif %}
 {%- endfor -%}
 {%- endfor -%}
 {%- endfor -%}

openapidocs/mk/v3/views_mkdocs/partial/path-items.html

@@ -26,7 +26,9 @@
 {% include "partial/request-body.html" %}
 {%- endif %}
 
+{%- if operation.responses %}
 {%- include "partial/request-responses.html" %}
+{%- endif %}
 {% endfor %}
 {% endfor %}
 {% endfor %}

tests/res/example4-split-output.md

@@ -195,7 +195,7 @@ Retrieve all users
             <td>string</td>
             <td></td>
             <td>No</td>
-            <td>Paginate through users by setting the cursor parameter to a nextCursor attribute returned by a previous request&#39;s response. Default value fetches the first &#34;page&#34; of the collection. See pagination for more detail.</td>
+            <td>Paginate through users by setting the cursor parameter to a nextCursor attribute returned by a previous request's response. Default value fetches the first "page" of the collection. See pagination for more detail.</td>
         </tr>
         <tr>
             <td class="parameter-name"><code>limit</code></td>

tests/res/example6-openapi.yaml

@@ -0,0 +1,22 @@
+# Example with requestBody component, see https://github.com/Neoteroi/essentials-openapi/issues/21
+openapi: 3.0.1
+info:
+  title: Test
+  version: v1
+paths:
+  "/something":
+    post:
+      requestBody:
+        $ref: "#/components/requestBodies/SomeBody"
+components:
+  requestBodies:
+    SomeBody:
+      description: Foo Bar.
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              a:
+                type: string

tests/res/example6-output.md

@@ -0,0 +1,50 @@
+<!--
+This Markdown has been generated by essentials-openapi
+https://github.com/Neoteroi/essentials-openapi
+
+Most likely, it is not desirable to edit this file by hand!
+-->
+
+# Test <span class="api-version">v1</span>
+
+
+## <span class="api-tag"></span>
+
+<hr class="operation-separator" />
+
+### <span class="http-post">POST</span> /something
+
+<p class="request-body-title"><strong>Request body</strong></p>
+
+
+
+=== "application/json"
+
+
+    ```json
+    {
+        "a": "string"
+    }
+    ```
+    <span class="small-note">⚠️</span>&nbsp;<em class="small-note warning">This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</em>
+
+
+
+    ??? hint "Schema of the request body"
+        ```json
+        {
+            "type": "object",
+            "properties": {
+                "a": {
+                    "type": "string"
+                }
+            }
+        }
+        ```
+
+
+
+
+
+
+---

tests/res/example7-openapi.yaml

@@ -0,0 +1,26 @@
+# https://github.com/Neoteroi/essentials-openapi/issues/24
+openapi: "3.0.2"
+info:
+  title: API Title
+  description: |
+    **Response**
+
+    ```json
+    [
+      {
+        "a": "b",
+        "c": {
+          "d": "e"
+        }
+      }
+    ]
+    ```
+  version: "1.0"
+servers:
+  - url: https://api.server.test/v1
+paths:
+  /test:
+    get:
+      responses:
+        '200':
+          description: OK

tests/res/example7-output.md

@@ -0,0 +1,56 @@
+<!--
+This Markdown has been generated by essentials-openapi
+https://github.com/Neoteroi/essentials-openapi
+
+Most likely, it is not desirable to edit this file by hand!
+-->
+
+# API Title <span class="api-version">1.0</span>
+
+**Response**
+
+```json
+[
+  {
+    "a": "b",
+    "c": {
+      "d": "e"
+    }
+  }
+]
+```
+<hr />
+## Servers
+
+<table>
+    <thead>
+        <tr>
+            <th>Description</th>
+            <th>URL</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>https://api.server.test/v1</td>
+            <td>
+                <a href="https://api.server.test/v1" target="_blank" rel="noopener noreferrer">https://api.server.test/v1</a>
+            </td>
+        </tr>
+    </tbody>
+</table>
+
+## <span class="api-tag"></span>
+
+<hr class="operation-separator" />
+
+### <span class="http-get">GET</span> /test
+
+
+<p class="response-title">
+    <strong>Response <span class="response-code code-200">200</span>&nbsp;<span class="status-phrase">OK</span></strong>
+</p>
+
+
+
+
+---

tests/test_mk_v3.py

@@ -289,3 +289,23 @@ def test_object_example_handler_handles_missing_pros():
     handler = ObjectExampleHandler()
 
     assert handler.get_example({}) == {}
+
+
+@pytest.mark.parametrize("example_file", ["example6", "example7"])
+def test_v3_markdown_yaml(example_file):
+    # example6
+    # https://github.com/Neoteroi/essentials-openapi/issues/21
+
+    # example7
+    # https://github.com/Neoteroi/essentials-openapi/issues/24
+    example_file_name = f"{example_file}-openapi.yaml"
+    data = get_file_yaml(example_file_name)
+    expected_result = get_resource_file_content(f"{example_file}-output.md")
+
+    handler = OpenAPIV3DocumentationHandler(
+        data, source=get_resource_file_path(example_file_name)
+    )
+
+    html = handler.write()
+
+    assert html == expected_result