Skip to main content

Sphinx extension allows you to test json apis

Project description


This extension makes it simple to add a widget allowing users to test JSON requests against your api form the documentation. It has support for parameters that get injected into the url path and to post JSON data to the api. It does not have support for query string parameters or form encoded post data (if you would like this, please add it and send a pull request).

There is support for client side json-schema validation (currently only for draft04). jsontest uses tv4 for schema validation. jsontest supports loading schemas from different files provided they can be accessed from the same host either using a relative path (e.g. sample.json) or a full path for the same host (e.g. /schemas/sample.json)

jsontest requires sphinxcontrib.httdomain documented apis and uses the dom to add events to elements on the page (it does expect a specific structure of the dom).

jsontest was designed for use with the readthedocs sphinx theme - it has not been tested with the other themes. If you want to sue the read the docs theme just set the html_theme in your

html_theme = 'sphinx_rtd_theme'


To install (assuming you have pip setup) just run:

pip install sphinxcontrib-jsontest

Then add sphinxcontrib.jsontest to your list of extensions in

extensions = ['sphinxcontrib.httpdomain', 'sphinxcontrib.jsontest']


To add teh test api functionality to an endpoint just add the directive in the block that generates the api endpoint (this is necessary because jsontest relies on a failry specific dom structure):

.. jsontest::

jsontest can’t figure out url args from the description yet, so if you rely on them you have to add them to the url_args option for the directive as a line separated list of key=value pairs (where value is the default value):

.. jsontest::

If you want to add a textarea for inputting json to the request just add the json_input option (with no argument):

.. jsontest::

And if you want to add a schema check to the json input add the schema option and pass the url or relative path to the schema file to validate against:

.. jsontest::
    :schema: schemas/test_input.json

You can combine the url_args, json_input and schema options.


The code is available as “public domain”, meaning that it is completely free to use, without any restrictions at all. Read the full license here.

It’s also available under an MIT license. MIT license

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-jsontest-0.1.5.tar.gz (19.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page