Fix #27, #28, improve tests

Neoteroi · May 1, 2023 · 3ae53d4 · 3ae53d4
1 parent c70519b
commit 3ae53d4
Show file tree

Hide file tree

Showing 12 changed files with 103 additions and 15 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@ htmlcov
 __pycache__
 *.egg-info
 *.tar.gz
+_test_files/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,14 @@ 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.7] - 2023-05-01 :toolbox:
+- Fixes [Markdown missing a newline after simple response types](https://github.com/Neoteroi/essentials-openapi/issues/27).
+- Fixes [Empty header when operations don't have any tag.](https://github.com/Neoteroi/essentials-openapi/issues/28).
+- When operations don't have any tag, the `h2` element
+- Improves tests.
+- Adopts `pyproject.toml`.
+- Workflow maintenance.
+
 ## [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;

diff --git a/openapidocs/__init__.py b/openapidocs/__init__.py
@@ -1 +1 @@
-VERSION = "1.0.6"
+VERSION = "1.0.7"
diff --git a/openapidocs/mk/v3/views_markdown/partial/path-items.html b/openapidocs/mk/v3/views_markdown/partial/path-items.html
@@ -1,9 +1,9 @@
 {% for tag, operations in handler.get_operations().items() %}
 
-## {{tag}}
+## {{tag or "Endpoints"}}
 
 {% for path, definition in operations %}
-{%- for http_method, operation in definition.items() -%}
+{%- for http_method, operation in definition.items() %}
 
 ### {{http_method.upper()}} {{path | safe}}
 {% if "summary" in operation -%}

diff --git a/openapidocs/mk/v3/views_mkdocs/partial/path-items.html b/openapidocs/mk/v3/views_mkdocs/partial/path-items.html
@@ -1,8 +1,8 @@
 {% for tag, operations in handler.get_operations().items() %}
-## <span class="api-tag">{{tag}}</span>
+## <span class="api-tag">{{tag or "Endpoints"}}</span>
 
 {% for path, definition in operations %}
-{%- for http_method, operation in definition.items() -%}
+{%- for http_method, operation in definition.items() %}
 <hr class="operation-separator" />
 
 ### <span class="http-{{http_method.lower()}}">{{http_method.upper()}}</span> {{path | route | safe}}

diff --git a/tests/common.py b/tests/common.py
@@ -1,5 +1,6 @@
 import json
 import os
+import re
 from typing import Any
 
 import pkg_resources
@@ -46,3 +47,21 @@ def get_file_json(file_name) -> Any:
 
 def get_file_yaml(file_name) -> Any:
     return yaml.safe_load(get_resource_file_content(file_name))
+
+
+def normalize_str(value: str) -> str:
+    return re.sub("\r?\n{2,}", "\n", value.strip())
+
+
+def compatible_str(value_one: str, value_two: str) -> bool:
+    """
+    Compares two strings ignoring multiple carriage returns and trailing carriage
+    returns. In HTML or Markdown it does not matter if you have multiple carriage
+    returns.
+    """
+    # first check if the two strings are equals: there is no point in stripping carriage
+    # returns otherwise
+    if value_one == value_two:
+        return True
+
+    return normalize_str(value_one) == normalize_str(value_two)
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -1,5 +1,8 @@
+import shutil
 from uuid import UUID
 
+from essentials.folders import ensure_folder
+
 from openapidocs.mk.v3.examples import IntegerExampleHandler, StringExampleHandler
 
 # override the UUID example generator to return the same value, so that tests can have
@@ -12,3 +15,10 @@
     "int32": lambda: 26,
     "int64": lambda: 26,
 }
+
+try:
+    shutil.rmtree("_test_files")
+except OSError:
+    pass
+
+ensure_folder("_test_files")
diff --git a/tests/res/example1-output-plain.md b/tests/res/example1-output-plain.md
@@ -27,6 +27,8 @@ Optional multiline or single-line description in
 
 ## Blobs
 
+
+
 ### POST /api/blobs/initialize-upload
 Initializes a file upload operation.
 
@@ -144,6 +146,8 @@ Refer to the common response description: [Unauthorized](#unauthorized)
 
 ## Categories
 
+
+
 ### GET /api/categories
 Gets the list of categories supported by the system.
 
@@ -253,6 +257,8 @@ _Other possible types: text/json, text/plain_
 
 ## Countries
 
+
+
 ### GET /api/countries
 Gets a list of countries of the World with English dislay names and ISO country
 codes.
@@ -292,6 +298,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### GET /api/system-countries
 Gets a list of countries supported by the system, with English dislay names and
 ISO country codes.
@@ -335,6 +343,8 @@ _Other possible types: text/json, text/plain_
 
 ## Downloads
 
+
+
 ### GET /api/downloads
 Gets a paginated set of downloads records.
 
@@ -473,6 +483,8 @@ _Other possible types: text/json, text/plain_
 
 ## Health
 
+
+
 ### GET /api/health
 API health check
 
@@ -524,6 +536,8 @@ _Other possible types: text/json, text/plain_
 
 ## Professionals
 
+
+
 ### GET /api/pro/own-context
 
 
@@ -596,6 +610,8 @@ _Other possible types: text/json, text/plain_
 
 ## Info
 
+
+
 ### GET /api/info
 Returns information about the API itself.
 
@@ -648,6 +664,8 @@ _Other possible types: text/json, text/plain_
 
 ## Releases
 
+
+
 ### GET /api/releases/{releaseId}
 Returns details about a release by id.
 
@@ -840,6 +858,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### DELETE /api/releases/{releaseId}
 Deletes a release by id.
 
@@ -850,7 +870,9 @@ Deletes a release by id.
 | AAD       | header | string | N/A     | No       | Access token issued by Azure Active Directory. |
 | releaseId | path   | string |         | No       |                                                |
 
-### Response 200 OK### PATCH /api/releases/{releaseId}
+### Response 200 OK
+
+### PATCH /api/releases/{releaseId}
 
 
 **Input parameters**
@@ -1105,6 +1127,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### GET /api/releases
 
 
@@ -1229,6 +1253,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### POST /api/releases
 
 
@@ -1320,6 +1346,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### GET /api/current-releases
 
 
@@ -1361,6 +1389,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### GET /api/orgs/current-releases
 
 
@@ -1402,6 +1432,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### GET /api/releases/{releaseId}/history
 
 
@@ -1504,6 +1536,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### GET /api/releases/{releaseId}/file/{nodeId}
 
 
@@ -1544,6 +1578,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### GET /api/releases/{releaseId}/file/{nodeId}/downloads
 
 
@@ -1584,6 +1620,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### PUT /api/releases/{releaseId}/files
 
 
@@ -1808,6 +1846,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### DELETE /api/releases/{releaseId}/files
 
 
@@ -2029,6 +2069,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### PUT /api/releases/{releaseId}/orgs
 
 
@@ -2259,6 +2301,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### DELETE /api/releases/{releaseId}/orgs
 
 
@@ -2479,6 +2523,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### POST /api/releases/{releaseId}/clone
 
 
@@ -2671,6 +2717,8 @@ _Other possible types: text/json, text/plain_
 }
 ```
 
+
+
 ### POST /api/releases/{releaseId}/publish
 
 

diff --git a/tests/res/example6-output.md b/tests/res/example6-output.md
@@ -8,7 +8,7 @@ Most likely, it is not desirable to edit this file by hand!
 # Test <span class="api-version">v1</span>
 
 
-## <span class="api-tag"></span>
+## <span class="api-tag">Endpoints</span>
 
 <hr class="operation-separator" />
 

diff --git a/tests/res/example7-output.md b/tests/res/example7-output.md
@@ -39,7 +39,7 @@ Most likely, it is not desirable to edit this file by hand!
     </tbody>
 </table>
 
-## <span class="api-tag"></span>
+## <span class="api-tag">Endpoints</span>
 
 <hr class="operation-separator" />
 

diff --git a/tests/test_cli.py b/tests/test_cli.py
@@ -11,7 +11,7 @@
 from openapidocs.mk.jinja import OutputStyle
 from openapidocs.utils.source import SourceError, read_from_source, read_from_url
 from openapidocs.utils.web import FailedRequestError, ensure_success, http_get
-from tests.common import get_file_json
+from tests.common import compatible_str, get_file_json
 
 from .serverfixtures import *  # noqa
 from .serverfixtures import BASE_URL
@@ -35,7 +35,7 @@ def remove_file(file_path: Path):
 
 
 def contents_equals(file_path_1, file_path_2):
-    assert read_file(file_path_1) == read_file(file_path_2)
+    assert compatible_str(read_file(file_path_1), read_file(file_path_2))
 
 
 def test_fetch_json(example_1_data):
@@ -107,7 +107,7 @@ def test_generate_docs_command_invalid_source():
     ],
 )
 def test_main_command_gen_mkdocs_docs(valid_source):
-    test_output = Path(f"{uuid4()}.md")
+    test_output = Path(f"_test_files/{uuid4()}.md")
     assert test_output.exists() is False
 
     runner = CliRunner()
@@ -184,7 +184,7 @@ def test_main_command_gen_plantuml_api_docs(valid_source):
 
 def test_main_command_gen_plain_markdown_docs():
     valid_source = "tests/res/example1-openapi.json"
-    test_output = Path(f"{uuid4()}.md")
+    test_output = Path(f"_test_files/{uuid4()}.md")
     assert test_output.exists() is False
 
     runner = CliRunner()