sphinxcontrib-httpdomain

Homepage:

https://github.com/sphinx-contrib/httpdomain

Documentation:

https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/

sphinxcontrib-httpdomain is useful to describe HTTP APIs. It provides Sphinx directives to document endpoints in a detailed way.

Example

GET /users/(int: user_id)/posts/(tag)

The posts tagged with tag that the user (user_id) wrote.

Example request:

GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
  {
    "post_id": 12345,
    "author_id": 123,
    "tags": ["server", "web"],
    "subject": "I tried Nginx"
  },
  {
    "post_id": 12346,
    "author_id": 123,
    "tags": ["html5", "standards", "web"],
    "subject": "We go to HTML 5"
  }
]
Query Parameters:
  • sort – one of hit, created-at

  • offset – offset number. default is 0

  • limit – limit number. default is 30

Request Headers:
  • Accept – the response content type depends on Accept header

  • Authorization – optional OAuth token to authenticate

Response Headers:
Status Codes:

Installation

pip install sphinxcontrib-httpdomain

Configuration

# conf.py
extensions = [
    '...',
    'sphinxcontrib.httpdomain',
]