• Swagger To Markdown Converter Online
• Swagger To Markdown Converter

Swagger API Docs Generator for Foliant¶

The static site on the picture was built with Slate backend together with SwaggerDoc preprocessor

This preprocessor generates Markdown documentation from Swagger spec files. It uses Jinja2 templating engine or Widdershins for generating Markdown from swagger spec files.

Crack Fuckers porn videos for free. Free apps for mac free download. CLICK HERE to watch sex films online without registration. The best Crack Fuckers porn collection online here at RunPorn.com. ./swagger-to-markdown.rb -r resources.json -p parameters.json -n Demo -o test.md -s pet.json or reading from a remote server. There are many articles on “building API document using swagger2” on the Internet. The document is an online document and needs to be accessed using HTTP. However, when we use the swagger interface document, sometimes we need to access the interface document offline, such as exporting the document to HTML and markdown format.

Installation¶

This preprocessor requires Widdershins to be installed on your system (unless you are using Foliant with Full Docker Image):

Config¶

To enable the preprocessor, add swaggerdoc to preprocessors section in the project config:

The preprocessor has a number of options:

spec_url

URL to Swagger spec file. If it is a list — preprocessor takes the first url which works.

spec_path

Local path to Swagger spec file (relative to project dir).

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.

mode

Determines how the Swagger spec file would be converted to markdown. Should be one of: jinja, widdershins. Default: widdershins

jinja Scanner utilities for mac. mode is deprecated. It may be removed in future

template

Only for jinja mode. Path to jinja-template for rendering the generated documentation. Path is relative to the project directory. If no template is specified preprocessor will use default template (and put it into project dir if it was missing). Default: swagger.j2

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 on widdershins parameters.

Usage¶

Add a <swaggerdoc></swaggerdoc> tag at the position in the document where the generated documentation should be inserted:

Each time the preprocessor encounters the tag <swaggerdoc></swaggerdoc> it inserts the whole generated documentation text instead of it. The path or url to Swagger spec file are taken from foliant.yml.

You can also specify some parameters (or all of them) in the tag options:

Tag parameters have the highest priority.

This way you can have documentation from several different Swagger spec files in one foliant project (even in one md-file if you like it so).

Customizing output¶

Widdershins¶

In widdershins mode the output markdown is generated by widdershins Node.js application. It supports customizing the output with doT.js templates.

Swagger To Markdown Converter Online

1. Clone the original widdershins repository and modify the templates located in one of the subfolders in the templates folder.
2. Save the modified templates somewhere near your foliant project.
3. Specify the path to modified templates in the user_templates field of the environment configuration. For example, like this:

Jinja¶

jinja mode is deprecated. It may be removed in future

In jinja mode the output markdown is generated by the Jinja2 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.

Swagger To Markdown Converter

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.