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: