https://github.com/foliant-docs/apidoc2markdown

Converter from Apidoc JSON to Markdown
https://github.com/foliant-docs/apidoc2markdown

Last synced: 5 months ago
JSON representation

Converter from Apidoc JSON to Markdown

• Host: GitHub
• URL: https://github.com/foliant-docs/apidoc2markdown
• Owner: foliant-docs
• License: mit
• Created: 2016-12-05T13:43:33.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2016-12-07T13:01:59.000Z (over 9 years ago)
• Last Synced: 2025-09-30T02:21:18.001Z (9 months ago)
• Language: Python
• Size: 2.93 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
###############

apidoc2markdown

###############

Apidoc_ is an open specification for documenting REST APIs in JSON or YAML.

Imperfect as it is, it's de facto a standard for many API developers.

This extension lets you render your swagger.json file as a Markdown document.

You can customize the output by providing your own Jinja2_ template.

.. important::

    For best results, disable Markdown processing when building Apidoc files:

    .. code-block:: shell

        $ apidoc -o docs -i myproject --markdown false # <- Do this.

        $ apidoc -o docs -i myproject                  # <- Instead of this.

    This way your markup will be preserved in the final Markdown output.

.. _Apidoc: http://apidocjs.com/

.. _Jinja2: http://jinja.pocoo.org/

.. warning::

    This extension was created for a particular project and thus is only

    guaranteed to work with this particular project! It is very much likely

    you'll have to modify apidoc.md.j2_ for your project.

.. _apidoc.md.j2: https://github.com/moigagoo/apidoc2markdown/blob/master/apidoc.md.j2

************

Installation

************

.. code-block:: shell

    $ pip install apidoc2markdown

*****

Usage

*****

.. code-block:: shell

    usage: apidoc2markdown-script.py [-h] [-i APIDOC_LOCATION] [-o OUTPUT]

                                    [-t TEMPLATE]

    optional arguments:

      -h, --help            show this help message and exit

      -i APIDOC_LOCATION, --input APIDOC_LOCATION

                            path to the directory with api_data.json

                            and api_project.json (default: .)

      -o OUTPUT, --output OUTPUT

                            path to the output Markdown file (default: swagger.md)

      -t TEMPLATE, --template TEMPLATE

                            Jinja2 template used for conversion