update readme, fix bug with jinja template

Author: minuhin

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018
+Copyright (c) 2020
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,18 +1,29 @@
-![](https://img.shields.io/pypi/v/foliantcontrib.swaggerdoc.svg)
+
+[![](https://img.shields.io/pypi/v/foliantcontrib.swaggerdoc.svg)](https://pypi.org/project/foliantcontrib.swaggerdoc/)  [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.swaggerdoc.svg?label=GitHub)](https://github.com/foliant-docs/foliantcontrib.swaggerdoc)
 
 # Swagger API Docs Generator for Foliant
 
-This preprocessor generates Markdown documentation from [Swagger](https://swagger.io/) spec files . It uses [Jinja2](http://jinja.pocoo.org/) templating engine or [widdershins](https://github.com/mermade/widdershins) for generating Markdown from swagger spec files.
+![](img/swagger.png)
+
+*The static site on the picture was built with [Slate](https://foliant-docs.github.io/docs/backends/slate/) backend together with SwaggerDoc preprocessor*
+
+This preprocessor generates Markdown documentation from [Swagger](https://swagger.io/) spec files. It uses [Jinja2](http://jinja.pocoo.org/) templating engine or [Widdershins](https://github.com/mermade/widdershins) for generating Markdown from swagger spec files.
 
 ## Installation
 
 ```bash
 $ pip install foliantcontrib.swaggerdoc
 ```
 
+This preprocessor requires [Widdershins](https://github.com/Mermade/widdershins) to be installed on your system (unless you are using [Foliant with Full Docker Image](https://foliant-docs.github.io/docs/tutorials/full_docker/)):
+
+```
+npm install -g widdershins
+```
+
 ## Config
 
-To enable the preprocessor, add `pgsqldoc` to `preprocessors` section in the project config:
+To enable the preprocessor, add `swaggerdoc` to `preprocessors` section in the project config:
 
 ```yaml
 preprocessors:
@@ -24,24 +35,22 @@ The preprocessor has a number of options:
 ```yaml
 preprocessors:
     - swaggerdoc:
-        json_url: http://localhost/swagger.json
-        json_path: swagger.json
+        spec_url: http://localhost/swagger.json
+        spec_path: swagger.json
         additional_json_path: tags.json
-        mode: 'jinja'
+        mode: widdershins
         template: swagger.j2
         environment: env.yaml
 
 ```
 
-`json_url`
+`spec_url`
 :    URL to Swagger spec file. If it is a list — preprocessor takes the first url which works.
 
-> even though the parameters are called *json*\_url and *json*\_path, yaml format is supported too. Parameters may be softly renamed in future.
-
-`json_path`
+`spec_path`
 :    Local path to Swagger spec file (relative to project dir).
 
-> If both url and path are specified — preprocessor first tries to fetch JSON from url, and then (if that fails) looks for the file on local path.
+> If both url and path are specified — preprocessor first tries to fetch spec from url, and then (if that fails) looks for the file on local path.
 
 `additional_json_path`
 :    Only for `jinja` mode. Local path to swagger spec file with additional info (relative to project dir). It will be merged into original spec file, *not overriding existing fields*.
@@ -78,12 +87,12 @@ You can also specify some parameters (or all of them) in the tag options:
 
 Introduction text for API documentation.
 
-<swaggerdoc json_url="http://localhost/swagger.json"
+<swaggerdoc spec_url="http://localhost/swagger.json"
             mode="jinja"
             template="swagger.j2">
 </swaggerdoc>
 
-<swaggerdoc json_url="http://localhost/swagger.json"
+<swaggerdoc spec_url="http://localhost/swagger.json"
             mode="widdershins"
             environment="env.yml">
 </swaggerdoc>
@@ -95,16 +104,6 @@ This way you can have documentation from several different Swagger spec files in
 
 ## Customizing output
 
-### Jinja
-
-> `jinja` mode is deprecated. It may be removed in future
-
-In `jinja` mode the output markdown is generated by the [Jinja2](http://jinja.pocoo.org/) template. In this template all fields from Swagger spec file are available under the dictionary named `swagger_data`.
-
-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`.
-
 ### Widdershins
 
 In `widdershins` mode the output markdown is generated by [widdershins](https://github.com/mermade/widdershins) Node.js application. It supports customizing the output with [doT.js](https://github.com/olado/doT) templates.
@@ -116,7 +115,17 @@ In `widdershins` mode the output markdown is generated by [widdershins](https://
 ```yaml
 preprocessors:
     - swaggerdoc:
-        json_path: swagger.yml
+        spec_path: swagger.yml
         environment:
             user_templates: !path ./widdershins_templates/
 ```
+
+### Jinja
+
+> `jinja` mode is deprecated. It may be removed in future
+
+In `jinja` mode the output markdown is generated by the [Jinja2](http://jinja.pocoo.org/) template. In this template all fields from Swagger spec file are available under the dictionary named `swagger_data`.
+
+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`.

changelog.md

@@ -1,3 +1,8 @@
+# 1.2.1
+
+- Fix spec path issue.
+- Fix: jinja mode default template wansn't copied.
+
 # 1.2.0
 
 - Add `spec_path` and `spec_url` parameters.

foliant/preprocessors/swaggerdoc/swaggerdoc.py

@@ -66,7 +66,7 @@ def __init__(self, *args, **kwargs):
 
     def _gather_specs(self,
                       urls: list,
-                      path_: PosixPath or None) -> PosixPath:
+                      path_: str or PosixPath or None) -> PosixPath:
         """
         Download first swagger spec from the url list; copy it into the
         temp dir and return path to it. If all urls fail — check path_ and
@@ -88,7 +88,7 @@ def _gather_specs(self,
 
         if path_:
             dest = self._swagger_tmp / f'swagger_spec'
-            if not path_.exists():
+            if not Path(path_).exists():
                 self._warning(f"Can't find file {path_}. Skipping.")
             else:  # file exists
                 copyfile(str(path_), str(dest))
@@ -107,10 +107,14 @@ def _process_jinja(self,
             else:
                 add = yaml.safe_load(open(additional, encoding="utf8"))
                 data = {**add, **data}
-
         if options.is_default('template') and not Path(options['template']).exists():
-            copyfile(resource_filename(__name__, 'template/' +
-                                       self.defaults['template']), options['template'])
+            copyfile(
+                resource_filename(
+                    __name__,
+                    'template/' + self.defaults['template']
+                ),
+                options['template']
+            )
         return self._to_md(data, options['template'])
 
     def _process_widdershins(self,
@@ -184,7 +188,8 @@ def process_swaggerdoc_blocks(self, block) -> str:
                                             ('json_path',),
                                             ('spec_url',),
                                             ('spec_path',)],
-                                  validators={'mode': validate_in(self._modes)})
+                                  validators={'mode': validate_in(self._modes)},
+                                  defaults=self.defaults)
         self.logger.debug(f'Processing swaggerdoc tag in {self.current_filepath}')
         spec_url = options['spec_url'] or options['json_url']
         if spec_url and isinstance(spec_url, str):

img/swagger.png

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