Sphinx directive for RESTful HTTP API examplesΒΆ

sphinxcontrib-httpexample enhances sphinxcontrib-httpdomain, a Sphinx domain extension for describing RESTful HTTP APIs in detail, with a simple call example directive. The new directive provided by this extension generates RESTful HTTP API call examples for different tools from a single HTTP request example.

The audience for this extension are developers and technical writes documenting their RESTful HTTP APIs. This extension has originally been developed for documenting plone.restapi.

  • Configuration:

    The URL scheme, either http or https, used in the generated examples can be configured with the httpexample_scheme configuration variable. It defaults to http.

    # conf.py
httpexample_scheme = 'https'

  • Syntax:

    .. http:example:: space separated list of tools
   :request: ../optional/rel/path/to/plaintext/request
   :response: ../optional/rel/path/to/plaintext/response

   Raw plaintext HTTP request example, which is
   required only when :request: is not specified.

  • Example:

    ..  http:example:: curl wget httpie python-requests

    GET /Plone/front-page HTTP/1.1
    Host: localhost:8080
    Accept: application/json
    Authorization: Basic YWRtaW46YWRtaW4=

  • Rendering:

    http

    GET /Plone/front-page HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=

    curl

    curl -i -X GET http://localhost:8080/Plone/front-page -H "Accept: application/json" --user admin:admin

    wget

    wget -S -O- http://localhost:8080/Plone/front-page --header="Accept: application/json" --auth-no-challenge --user=admin --password=admin

    httpie

    http http://localhost:8080/Plone/front-page Accept:application/json -a admin:admin

    python-requests

    requests.get('http://localhost:8080/Plone/front-page', headers={'Accept': 'application/json'}, auth=('admin', 'admin'))

  • Supported tools: