foliantcontrib.swaggerdoc 1.0.0

Documentation generator for Swagger API

Swagger API Docs Generator for Foliant

This preprocessor generates Markdown documentation from JSON generated by Swagger. It uses Jinja2 templating engine for customizing the layout.

Installation

$ pip install foliantcontrib.swaggerdoc

Config

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

preprocessors:
    - swaggerdoc

The preprocessor has a number of options:

preprocessors:
    - swaggerdoc:
        swagger_json_urls: http://localhost/swagger.json
        swagger_json_paths: swagger.json
        template: swagger.j2

swagger_json_urls : URL to JSON generated by Swagger or several such urls (in this case use yaml list format).

swagger_json_paths : path to JSON generated by Swagger relative to project dir or several such paths (in this case use yaml list format).

Important notice about those json files. Preprocessor would start parsing JSONS from the first url, subsequently merging data from following JSONS in the same order they are declared in config. First URLs, then paths.

template : Path to jinja-template for rendering the generated documentation. Path is relative to the project directory. Default: swagger.j2

Usage

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

# Introduction

This document contains the automatically generated documentation of our API.

<<swaggerdoc></swaggerdoc>

Each time the preprocessor encounters the tag <<swaggerdoc></swaggerdoc> it inserts the whole generated documentation text instead of it. The paths or urls to swagger.json are taken from the config-file.

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

# Introduction

Introduction text for API documentation.

<swaggerdoc swagger_json_urls="http://localhost/swagger.json"
            template="swagger.j2">
</swaggerdoc>

Tag parameters have the highest priority.

Use comma to have several urls\paths in tag options.

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