add: strict behavior and tests (#4)

* add: strick option

* add: test and fix preprocessor

* bump version

* fix: README.md

* add: yaml test

Author: TOsmanov

.github/workflows/python-test.yml

@@ -0,0 +1,27 @@
+name: Python package
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip3 install .
+          pip3 install --upgrade foliantcontrib.test_framework
+          npm install -g widdershins
+      - name: Test with unittest
+        run: |
+          python3 -m unittest discover

.gitignore

@@ -100,4 +100,5 @@ ENV/
 # mypy
 .mypy_cache/
 
-.DS_store
+.DS_store
+.swaggercache

README.md

@@ -40,7 +40,7 @@ preprocessors:
         mode: widdershins
         template: swagger.j2
         environment: env.yaml
-
+        strict: false
 ```
 
 `spec_url`
@@ -65,6 +65,9 @@ preprocessors:
 `environment`
 :   Only for `widdershins` mode. Parameters for widdershins converter. You can either pass a string containing relative path to YAML or JSON file with all parameters (like in example above) or specify all parameters in YAML format under this key. [More info](https://github.com/mermade/widdershins) on widdershins parameters.
 
+`strict`
+:   If the `strict` option is enabled, then if a critical error is detected, the build will be aborted after applying the preprocessor.
+
 ## Usage
 
 Add a `<swaggerdoc></swaggerdoc>` tag at the position in the document where the generated documentation should be inserted:
@@ -128,3 +131,15 @@ In `jinja` mode the output markdown is generated by the [Jinja2](http://jinja.po
 To customize the output create a template which suits your needs. Then supply the path to it in the `template` parameter.
 
 If you wish to use the default template as a starting point, build the foliant project with `swaggerdoc` preprocessor turned on. After the first build the default template will appear in your foliant project dir under name `swagger.j2`.
+
+## Tests
+
+To run the tests locally, you will need to install NodeJS.
+If you have NodeJS installed, then run:
+```bash
+./test.sh
+```
+Alternatively, you can also use a Docker to run the tests. To do so, run:
+```bash
+./test_in_docker.sh
+```

changelog.md

@@ -1,3 +1,7 @@
+# 1.2.6
+
+- Add: strict behavior option and tests
+
 # 1.2.5
 
 - Fix: a specific version of ruamel.yaml was used

foliant/preprocessors/swaggerdoc/swaggerdoc.py

@@ -28,7 +28,7 @@
 from foliant.contrib.combined_options import validate_in
 from foliant.preprocessors.utils.preprocessor_ext import BasePreprocessorExt
 from foliant.preprocessors.utils.preprocessor_ext import allow_fail
-
+from foliant.utils import output
 
 class Preprocessor(BasePreprocessorExt):
     tags = ('swaggerdoc',)
@@ -40,7 +40,8 @@ class Preprocessor(BasePreprocessorExt):
         'json_path': '',  # deprecated
         'spec_path': '',
         'mode': 'widdershins',
-        'template': 'swagger.j2'
+        'template': 'swagger.j2',
+        'strict': True
     }
 
     def __init__(self, *args, **kwargs):
@@ -87,8 +88,14 @@ def _gather_specs(self,
                     self.logger.debug(f'Using spec from {url} ({filename})')
                     return filename
                 except (HTTPError, URLError) as e:
-                    self._warning(f'\nCannot retrieve swagger spec file from url {url}. Skipping.',
-                                  error=e)
+                    msg = f'\nCannot retrieve swagger spec file from url {url}.'
+                    if self.options['strict']:
+                        self.logger.error(msg)
+                        output(f'ERROR: {msg}')
+                        os._exit(1)
+                    else:
+                        self._warning(f'{msg}. Skipping.',
+                                    error=e)
         local_path = Path(path_)
         if local_path:
             # dest = self._swagger_tmp / f'swagger_spec'

setup.py

@@ -16,7 +16,7 @@
     description=SHORT_DESCRIPTION,
     long_description=LONG_DESCRIPTION,
     long_description_content_type='text/markdown',
-    version='1.2.5',
+    version='1.2.6',
     author='Daniil Minukhin',
     author_email='[email protected]',
     packages=['foliant.preprocessors.swaggerdoc'],

test.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# before testing make sure that you have installed the fresh version of preprocessor:
+pip3 install .
+# also make sure that fresh version of test framework is installed:
+pip3 install --upgrade foliantcontrib.test_framework
+
+# install dependencies
+npm install -g widdershins
+
+python3 -m unittest discover -v

test_in_docker.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Write Dockerfile
+echo "FROM python:3.9.21-alpine3.20" > Dockerfile
+echo "RUN apk add --no-cache --upgrade bash && pip install --no-build-isolation pyyaml==5.4.1" >> Dockerfile
+echo "RUN apk add nodejs npm" >> Dockerfile
+
+# Run tests in docker
+docker build . -t test-swaggerdoc:latest
+
+docker run --rm -it -v "./:/app/" -w /app/ test-swaggerdoc:latest "./test.sh"
+
+# Remove Dockerfile
+rm Dockerfile