sphinxcontrib-swagger2sphinx 0.1.0

Converter from Swagger to Sphinx HTTP domain.

Swagger 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 Sphinx document. It uses HTTP domain directives for paths and a glossary for definitions.

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 swagger-api.rst for your project.

Usage

1. Install the extension:

   $ pip install sphinxcontrib-swagger2sphinx

2. Copy the content of swagger-api.rst to the file where you want your Swagger file rendered.

3. Add the extension to your conf.py:

   extensions = [
       'sphinxcontrib.swagger2sphinx',
       ...
   ]

4. Specify the path to your Swagger file in conf.py. It can be a local path or a URL:

   swagger2sphinx_swagger_location = "swagger.json"
   # swagger2sphinx_swagger_location = "http://example.com/swagger.json"

Testimonials

Thanks to Eric Holscher for writing an excellent blog post about extending Sphinx with Jinja2 templating.