sphinxcontrib-httpdomain

https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/
Admin
A Sphinx domain extension that provides directives and roles for documenting HTTP APIs with support...
Tokens:11,963
Snippets:133
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example HTTP POST Directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

A comprehensive example demonstrating the use of various resource fields within an HTTP POST directive, including parameters, headers, and status codes.

```rst
.. http:post:: /posts/(int:post_id)

   Replies a comment to the post.

   :param post_id: post's unique id
   :type post_id: int
   :form email: author email address
   :form body: comment body
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :status 302: and then redirects to :http:get:`/posts/(int:post_id)`
   :status 400: when form parameters are missing

.. http:get:: /posts/(int:post_id)

   Fetches the post

   (...)
```

--------------------------------

### Documenting an HTTP GET Endpoint

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

This directive describes an HTTP GET endpoint, including its path with parameter types, a description, example request and response, query parameters, request headers, response headers, and status codes. Use this to document specific API endpoints.

```http
.. http:get:: /users/(int:user_id)/posts/(tag)

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

   **Example request**:

   .. sourcecode:: http

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

   **Example response**:

   .. sourcecode:: http

      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 sort: one of ``hit``, ``created-at``
   :query offset: offset number. default is 0
   :query limit: limit number. default is 30
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :statuscode 200: no error
   :statuscode 404: there's no user

```

--------------------------------

### GET /

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Retrieves the home page of the application.

```APIDOC
## GET /

### Description
Home page.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **Status** (integer) - 200 OK
```

--------------------------------

### Document HTTP GET Resource

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use the http:get directive to document an API endpoint with request and response examples.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)

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

   **Example request**:

   .. sourcecode:: http

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

   **Example response**:

   .. sourcecode:: http

      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 sort: one of ``hit``, ``created-at``
   :query offset: offset number. default is 0
   :query limit: limit number. default is 30
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :statuscode 200: no error
   :statuscode 404: there's no user
```

--------------------------------

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

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Example of a GET request to retrieve posts for a specific user and tag.

```APIDOC
## GET /users/(int:user_id)/posts/(tag)

### Description
Retrieves posts for a specific user, filtered by a tag.

### Method
GET

### Endpoint
`/users/(int:user_id)/posts/(tag)`

### Parameters
#### Path Parameters
- **user_id** (int) - Required - The ID of the user.
- **tag** (string) - Required - The tag to filter posts by.

#### Query Parameters
- **sort** (string) - Optional - Specifies the sorting order. Allowed values: `hit`, `created-at`.
- **offset** (int) - Optional - The number of results to skip. Defaults to 0.
- **limit** (int) - Optional - The maximum number of results to return. Defaults to 30.

#### Request Headers
- **Accept** (string) - Optional - Determines the response content type.
- **Authorization** (string) - Optional - An OAuth token for authentication.

### Response
#### Success Response (200)
- **post_id** (integer) - The unique identifier for the post.
- **author_id** (integer) - The ID of the post's author.
- **tags** (array of strings) - A list of tags associated with the post.
- **subject** (string) - The subject or title of the post.

#### Error Response
- **404** - Returned when the specified user does not exist.

### Request Example
```json
{
  "post_id": 12345,
  "author_id": 123,
  "tags": ["server", "web"],
  "subject": "I tried Nginx"
}
```

### Response Example (200 OK)
```json
[
  {
    "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"
  }
]
```
```

--------------------------------

### GET /

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/http-routingtable.html

Root endpoint for the application.

```APIDOC
## GET /

### Description
Retrieves the root resource.

### Method
GET

### Endpoint
/
```

--------------------------------

### HTTP GET Directive with 'synopsis' Option

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Illustrates adding a short description to an HTTP GET endpoint using the ':synopsis:' option. This description appears in the generated routing table.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :synopsis: Returns posts by the specified tag for the user
```

--------------------------------

### HTTP GET Directive with synopsis Option

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Provide a short description for an HTTP GET endpoint in the routing table using the :synopsis: option.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :synopsis: Returns posts by the specified tag for the user

```

--------------------------------

### Bottle Integration

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Instructions and examples for integrating the Bottle autohttp extension with Sphinx.

```APIDOC
## ..autobottle:: module:app

### Description
Generates HTTP API references from a Bottle application. It takes an import name, like:

    your.webapplication.module:app

Colon character (``:``) separates module path and application variable. Latter part can be more complex:

    your.webapplication.module:create_app(config='default.cfg')

It's useful when a Bottle application is created from the factory function (:func:`create_app`, in the above example).

### Parameters
#### Directive Options
- **endpoints** (list of strings) - Optional - Endpoints to generate a reference. If omitted or empty, all endpoints are documented.
- **undoc-endpoints** (list of strings) - Optional - Excludes specified endpoints from generated references.
- **include-empty-docstring** (flag) - Optional - Includes view functions that don't have docstrings.

### Request Example
```rst
.. autobottle:: autobottle_sampleapp:app
   :endpoints: user, post, friends
```

### Response Example
(No specific response examples are provided in the documentation, as this directive generates documentation content within Sphinx.)
```

--------------------------------

### Tornado Integration

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Instructions and examples for integrating the Tornado autohttp extension with Sphinx.

```APIDOC
## ..autotornado:: module:app

### Description
Generates HTTP API references from a Tornado application's routing table. It takes an import name, like:

    your.webapplication.module:app

Colon character (``:``) separates module path and application variable.

### Parameters
#### Directive Options
- **endpoints** (list of strings) - Optional - Endpoints to generate a reference. If omitted or empty, all endpoints are documented.
- **undoc-endpoints** (list of strings) - Optional - Excludes specified endpoints from generated references.
- **include-empty-docstring** (flag) - Optional - Includes view functions that don't have docstrings.

### Request Example
```rst
.. autotornado:: yourwebapp:app
   :endpoints: User.get, User.post, Friends.get
```

### Response Example
(No specific response examples are provided in the documentation, as this directive generates documentation content within Sphinx.)
```

--------------------------------

### Specify Tornado application import path

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Example of specifying the module path and application variable.

```rst
your.webapplication.module:app
```

--------------------------------

### GET /

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Home page endpoint.

```APIDOC
## GET /

### Description
Home page.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **Status** (string) - OK
```

--------------------------------

### Define Flask route with quick reference annotation

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

This Python code demonstrates how to define a Flask route with a docstring that includes the '.. :quickref:' annotation. The '<resource>' is 'User' and the '<short description>' is 'Get Profile Page'. This annotation is used by the 'qrefflask' directive to generate a quick API reference table.

```python
@app.route('/<user>')
def user(user):
    """User profile page.

    .. :quickref: User; Get Profile Page

    my docco here
    """
    return 'hi, ' + user
```

--------------------------------

### HTTP GET Directive with 'addtoc' Option

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Example of using the ':addtoc:' option with an HTTP GET directive. This adds the API endpoint to the page-level table of contents.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :addtoc:
```

--------------------------------

### Generate quick API reference table for Flask app

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

The 'qrefflask' directive is used to generate a quick API reference table from a Flask application. This example shows its basic usage with the 'autoflask_sampleapp' and the 'undoc-static' option to exclude static file serving routes.

```rst
.. qrefflask:: autoflask_sampleapp:app
   :undoc-static:
```

--------------------------------

### Reference an HTTP GET Directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

You can reference an HTTP GET directive using the ':http:get:' role, followed by the endpoint path. This is useful for linking to API documentation within your Sphinx project.

```rst
:http:get:`/users/(int:user_id)/posts/(tag)`
```

--------------------------------

### Referencing HTTP GET Directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Example of referencing an HTTP GET directive within reStructuredText. This is useful for linking to specific API endpoints documented elsewhere.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
```

--------------------------------

### HTTP GET Directive with 'noindex' Option

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Demonstrates how to use the ':noindex:' option with an HTTP GET directive. This prevents the directive from being included in the HTTP routing table.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :noindex:
```

--------------------------------

### HTTP GET Directive with 'deprecated' Option

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Shows how to mark an HTTP GET method as deprecated using the ':deprecated:' option. This is useful for indicating that an API endpoint is no longer recommended for use.

```rst
.. http:get:: /users/(int:user_id)/tagged_posts
   :deprecated:
```

--------------------------------

### GET /<user>

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Retrieves the user profile page for a given user.

```APIDOC
## GET /<user>

### Description
User profile page.

### Method
GET

### Endpoint
/<user>

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name

### Response
#### Success Response (200)
- **status** (string) - when user exists

#### Error Response (404)
- **status** (string) - when user doesn't exist
```

--------------------------------

### Filter Bottle endpoints

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Examples of using the endpoints and undoc-endpoints flags to control documentation output.

```rst
.. autobottle:: yourwebapp:app
   :endpoints: user, post, friends
```

```rst
.. autobottle:: yourwebapp:app
   :endpoints:
```

```rst
.. autobottle:: yourwebapp:app
   :undoc-endpoints: admin, admin_login
```

--------------------------------

### GET /<user>

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

User profile page endpoint.

```APIDOC
## GET /<user>

### Description
User profile page.

### Method
GET

### Endpoint
/<user>

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name

### Response
#### Success Response (200)
- **Status** (string) - OK - when user exists

#### Error Response (404)
- **Status** (string) - Not Found - when user doesn't exist
```

--------------------------------

### HTTP GET Directive with deprecated Option

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Mark an HTTP GET method as deprecated in the routing table using the :deprecated: option.

```rst
.. http:get:: /users/(int:user_id)/tagged_posts
   :deprecated:

```

--------------------------------

### Filter Tornado endpoints

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Examples of using the endpoints and undoc-endpoints flags to control documentation output.

```rst
.. autotornado:: yourwebapp:app
   :endpoints: User.get, User.post, Friends.get
```

```rst
.. autotornado:: yourwebapp:app
   :endpoints:
```

```rst
.. autotornado:: yourwebapp:app
   :undoc-endpoints: admin, admin_login
```

--------------------------------

### Referencing Routing Table

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Example of referencing the generated routing table using the :ref:`routingtable` role. This is typically used to link to a summary of all documented API endpoints.

```rst
.. ref::routingtable
```

--------------------------------

### HTTP GET Directive with addtoc Option

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Include HTTP API endpoint elements in the page-level table of contents by using the :addtoc: option.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :addtoc:

```

--------------------------------

### GET /<user>/posts/<int:post_id>

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Retrieves a specific post for a given user.

```APIDOC
## GET /<user>/posts/<int:post_id>

### Description
User's post.

### Method
GET

### Endpoint
/<user>/posts/<int:post_id>

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name
- **post_id** (int) - Required - post unique id

### Response
#### Success Response (200)
- **status** (string) - when user and post exists

#### Error Response (404)
- **status** (string) - when user and post doesn't exist
```

--------------------------------

### GET /posts/(int:post_id)

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Fetches a specific post by its unique ID.

```APIDOC
## GET /posts/(int:post_id)

### Description
Fetches the post.

### Method
GET

### Endpoint
/posts/(int:post_id)

### Parameters
#### Path Parameters
- **post_id** (int) - Required - post's unique id
```

--------------------------------

### HTTP Method Directives

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Directives for describing various HTTP methods like GET, POST, PUT, DELETE, etc.

```APIDOC
## HTTP Method Directives

This section describes the directives used to document HTTP methods for a resource.

### Directives

- **.. http:options:: path**
  Describes the :http:method:`OPTIONS` method for a resource.

- **.. http:head:: path**
  Describes the :http:method:`HEAD` method for a resource.

- **.. http:post:: path**
  Describes the :http:method:`POST` method for a resource.

- **.. http:get:: path**
  Describes the :http:method:`GET` method for a resource.

- **.. http:put:: path**
  Describes the :http:method:`PUT` method for a resource.

- **.. http:patch:: path**
  Describes the :http:method:`PATCH` method for a resource.

- **.. http:delete:: path**
  Describes the :http:method:`DELETE` method for a resource.

- **.. http:trace:: path**
  Describes the :http:method:`TRACE` method for a resource.

- **.. http:copy:: path**
  Describes the :http:method:`COPY` method for a resource. (Added in 1.3.0)

- **.. http:any:: path**
  Describes a resource that accepts requests with any HTTP method. (Added in 1.3.0)

### Options

Custom options can be applied to these directives:

- **:noindex:**
  Excludes the directive from the HTTP routing table.
  .. sourcecode:: rst

     .. http:get:: /users/(int:user_id)/posts/(tag)
        :noindex:

- **:deprecated:**
  Marks the method as deprecated in the HTTP routing table.
  .. sourcecode:: rst

     .. http:get:: /users/(int:user_id)/tagged_posts
        :deprecated:

- **:synopsis: <text>**
  Adds a short description for the HTTP routing table.
  .. sourcecode:: rst

     .. http:get:: /users/(int:user_id)/posts/(tag)
        :synopsis: Returns posts by the specified tag for the user

- **:addtoc:**
  Adds HTTP API endpoint elements to the page-level table of contents. (Added in 2.0.0)
  .. sourcecode:: rst

     .. http:get:: /users/(int:user_id)/posts/(tag)
        :addtoc:

```

--------------------------------

### GET /<user>/posts/<post_id>

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

User's post endpoint.

```APIDOC
## GET /<user>/posts/<post_id>

### Description
User's post.

### Method
GET

### Endpoint
/<user>/posts/<post_id>

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name
- **post_id** (int) - Required - post unique id

### Response
#### Success Response (200)
- **Status** (string) - OK - when user and post exists

#### Error Response (404)
- **Status** (string) - Not Found - when user and post doesn't exist
```

--------------------------------

### GET /(?P<user>[a-z0-9]+)

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Retrieves the user profile page for a specific user.

```APIDOC
## GET /(?P<user>[a-z0-9]+)

### Description
User profile page.

### Method
GET

### Endpoint
/(?P<user>[a-z0-9]+)

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name

### Response
#### Success Response (200)
- **Status** (integer) - 200 OK

#### Error Response (404)
- **Status** (integer) - 404 Not Found - when user doesn't exist
```

--------------------------------

### GET /(?P<user>[a-z0-9]+)/posts/(?P<post_id>[\d+]+)

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Retrieves a specific post for a given user.

```APIDOC
## GET /(?P<user>[a-z0-9]+)/posts/(?P<post_id>[\d+]+)

### Description
User's post.

### Method
GET

### Endpoint
/(?P<user>[a-z0-9]+)/posts/(?P<post_id>[\d+]+)

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name
- **post_id** (integer) - Required - post unique id

### Response
#### Success Response (200)
- **Status** (integer) - 200 OK

#### Error Response (404)
- **Status** (integer) - 404 Not Found - when user and post doesn't exist
```

--------------------------------

### GET /users/{user_id}/posts/{tag}

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Retrieves posts tagged with a specific tag for a given user.

```APIDOC
## GET /users/(int:user_id)/posts/(tag)

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

### Method
GET

### Endpoint
/users/(int:user_id)/posts/(tag)

### Parameters
#### Query Parameters
- **sort** (string) - Optional - one of ``hit``, ``created-at``
- **offset** (integer) - Optional - offset number. default is 0
- **limit** (integer) - Optional - limit number. default is 30

#### Request Headers
- **Accept** (string) - Required - the response content type depends on :mailheader:`Accept` header
- **Authorization** (string) - Optional - optional OAuth token to authenticate

### Request Example
```http
GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Authorization: Bearer your_token_here
```

### Response
#### Success Response (200)
- **Content-Type** (string) - this depends on :mailheader:`Accept` header of request

#### Response Example
```http
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"
  }
]
```

#### Error Response (404)
- **message** (string) - Indicates that the user was not found.
```

--------------------------------

### Clone the httpdomain repository

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use these commands to download the source code and navigate into the project directory.

```console
$ git clone https://github.com/sphinx-contrib/httpdomain.git
$ cd httpdomain
```

--------------------------------

### Configure Sphinx for Bottle

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Add the extension to the extensions list in your conf.py file.

```python
extensions = ['sphinxcontrib.autohttp.bottle']
```

--------------------------------

### Configure Sphinx for Tornado

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Add the extension to the extensions list in your conf.py file.

```python
extensions = ['sphinxcontrib.autohttp.tornado']
```

--------------------------------

### Typed Query Parameters

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Demonstrates how to specify types for query parameters within an HTTP resource description. This improves clarity and can aid in validation.

```rst
:query string title: the post title
:query string body: the post body
:query boolean sticky: whether it's sticky or not
```

--------------------------------

### Document Flask App with autoflask

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use the autoflask directive to generate API documentation from a Flask application instance.

```rst
.. autoflask:: autoflask_sampleapp:app
   :undoc-static:
```

--------------------------------

### Basic Autoflask Directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Use the 'autoflask' directive to generate API documentation from a Flask application. Specify the application import name and optionally disable documentation for static files.

```rst
.. autoflask:: autoflask_sampleapp:app
   :undoc-static:

```

--------------------------------

### Configure HTTP Index Names

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Set the short and full names for the API index.

```python
http_index_shortname = 'api'
```

```python
http_index_localname = "My Project HTTP API"
```

--------------------------------

### Resource Fields

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Describes how to document parameters for HTTP resources using field lists.

```APIDOC
## Resource Fields

Field lists within HTTP resource description directives are used to document parameters.

### Recognized Fields

- **param, parameter, arg, argument**: Describes URL parameters.

- **queryparameter, queryparam, qparam, query**: Describes parameters passed in the query string. These can optionally be typed.
  .. versionchanged:: 1.1.9

  Example with types:
  .. sourcecode:: rst

     :query string title: the post title
     :query string body: the post body
     :query boolean sticky: whether it's sticky or not

- **formparameter, formparam, fparam, form**: Describes parameters passed in the request content body, encoded as `application/x-www-form-urlencoded` or `multipart/form-data`.

### Example Usage

.. sourcecode:: rst

   .. http:get:: /users/(int:user_id)/posts
      :query sort: one of `hit`, `created-at`
      :query offset: offset number. default is 0
      :query limit: limit number. default is 30
      :reqheader Accept: the response content type depends on :mailheader:`Accept` header
      :reqheader Authorization: optional OAuth token to authenticate
      :statuscode 200: no error
      :statuscode 404: there's no user

```

--------------------------------

### autoflask Directive Options

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Options available for the .. autoflask:: directive, used for documenting Flask applications.

```APIDOC
## autoflask Directive Options

This section details the various options that can be used with the `.. autoflask::` directive.

### Options

- **undoc-endpoints** (boolean) - Excludes specified endpoints from generated references. This option is distinct from docstrings and focuses on excluding specific endpoints.

- **blueprints** (list) - Only include specified blueprints in generated references.
  .. versionadded:: 1.1.9

- **undoc-blueprints** (list) - Excludes specified blueprints from generated references.
  .. versionadded:: 1.1.8

- **modules** (list) - Only include specified view modules in generated references.
  Example:
  .. sourcecode:: rst

     .. autoflask:: yourwebapp:app
        :modules: yourwebapp.views.admin

  .. versionadded:: 1.5.0

- **undoc-modules** (list) - Excludes specified view modules from generated references.
  .. versionadded:: 1.5.0

- **undoc-static** (boolean) - Excludes a view function that serves static files.

- **order** (string) - Determines the order in which endpoints are listed. Currently, only `path` is supported.
  Example:
  .. sourcecode:: rst

     .. autoflask:: yourwebapp:app
        :endpoints:
        :order: path

  .. versionadded:: 1.5.0

- **groupby** (string) - Determines the strategy to group paths. Currently, only `view` is supported, grouping paths by their view functions.
  .. versionadded:: 1.6.0

- **include-empty-docstring** (boolean) - If set, includes view functions that do not have a docstring.
  .. versionadded:: 1.1.2

### Endpoint Naming Convention

Endpoint names applied to blueprints are prefixed with the blueprint's name (e.g., `blueprint.endpoint`).
```

--------------------------------

### Specify Flask Application Import Path

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Provide the module path and application variable, optionally including factory function arguments.

```rst
your.webapplication.module:app
```

```rst
your.webapplication.module:create_app(config='default.cfg')
```

--------------------------------

### Configure Sphinx Extensions

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Add the extension to the extensions list in your conf.py file.

```python
extensions = ['sphinxcontrib.httpdomain']
```

--------------------------------

### Configure Sphinx extensions for Flask API reference

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

To use the 'sphinxcontrib.autohttp.flaskqref' module for generating quick API references, both 'sphinxcontrib.autohttp.flask' and 'sphinxcontrib.autohttp.flaskqref' must be added to the 'extensions' list in your Sphinx configuration file (conf.py).

```python
extensions = ['sphinxcontrib.autohttp.flask',
              'sphinxcontrib.autohttp.flaskqref']
```

--------------------------------

### Reference HTTP Methods

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Use the `:http:method:` role to reference HTTP methods (verbs). In HTML output, this text becomes a hyperlink to a web reference for the specified HTTP method. This role is useful for specifying allowed methods.

```rst
It accepts :http:method:`post` only.

```

--------------------------------

### Use autobottle directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Basic usage of the autobottle directive to document a Bottle application.

```rst
.. autobottle:: autobottle_sampleapp:app
```

--------------------------------

### Include Endpoints with Empty Docstrings

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Use the `:include-empty-docstring:` flag with `autotornado` to include view functions that lack docstrings.

```rst
.. autotornado:: yourwebapp:app
   :include-empty-docstring:
```

--------------------------------

### Configure HTTP Header Ignore Prefixes

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Define a list of HTTP header prefixes to ignore in strict mode.

```python
http_headers_ignore_prefixes = ['X-']
```

--------------------------------

### sphinxcontrib.autohttp.bottle Module

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Documentation for the `sphinxcontrib.autohttp.bottle` module, which exports API references from Bottle applications.

```APIDOC
## :mod:`sphinxcontrib.autohttp.bottle` --- Exporting API reference from Bottle app

This module generates RESTful HTTP API reference documentation from a Bottle application's routing table, similar to how :mod:`sphinx.ext.autodoc` works for Python code.
```

--------------------------------

### qrefflask Directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

The `.. qrefflask::` directive generates a quick API reference table for Flask routes.

```APIDOC
## .. qrefflask:: Directive

This directive generates HTTP API references from a Flask application and places them in a list-table with quick reference links. It requires both `sphinxcontrib.autohttp.flask` and `sphinxcontrib.autohttp.flaskqref` to be added to your Sphinx configuration's extensions.

### Usage

.. rst:directive:: .. qrefflask:: module:app

   .. versionadded:: 1.5.0

   Generates HTTP API references from a Flask application and places these in a list-table with quick reference links. The usage and options are identical to that of :mod:`sphinxcontrib.autohttp.flask` with the addition of the ``autoquickref`` option.

### Basic Usage

Place the quick reference table near the top of your documentation. Routes intended for the quick reference table require a specific rst comment in their docstring unless the ``autoquickref`` option is used:

.. sourcecode:: rst

    .. :quickref: [<resource>;] <short description>

- **<resource>** (optional): The resource name for grouping operations. If omitted, operations are grouped by the first line of the docstring when ``autoquickref`` is enabled.
- **<short description>** (required): A brief description of the operation.

When the ``autoquickref`` option is used, all routes must be within blueprints. The ``<resource>`` will be the blueprint's name, and the ``<short description>`` will be the first line of the docstring.

Example:

.. sourcecode:: python

    @app.route('/<user>')
    def user(user):
        """User profile page.

        .. :quickref: User; Get Profile Page

        my docco here
        """
        return 'hi, ' + user

### Example Usage

.. sourcecode:: rst

   .. qrefflask:: autoflask_sampleapp:app
      :undoc-static:

This directive can also be used with the `:undoc-static:` option to exclude static file serving routes.
```

--------------------------------

### Configure Flask Extension in Sphinx

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Add the extension to the extensions list in your conf.py file.

```python
extensions = ['sphinxcontrib.autohttp.flask']
```

--------------------------------

### Configure HTTP Strict Mode

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Enable or disable build errors for non-standard status codes, methods, and headers.

```python
http_strict_mode = True
```

--------------------------------

### Autoflask Directive with Options

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Customize the 'autoflask' directive using options like 'endpoints', 'undoc-endpoints', 'blueprints', 'undoc-blueprints', 'modules', 'undoc-modules', 'undoc-static', 'order', 'groupby', and 'include-empty-docstring'.

```rst
.. autoflask:: yourwebapp:app
   :endpoints: user, post, friends

```

```rst
.. autoflask:: yourwebapp:app
   :endpoints:

```

```rst
.. autoflask:: yourwebapp:app
   :undoc-endpoints: admin, admin_login

```

```rst
.. autoflask:: yourwebapp:app
   :modules: yourwebapp.views.admin

```

```rst
.. autoflask:: yourwebapp:app
   :endpoints:
   :order: path

```

--------------------------------

### Configure HTTP Index Ignore Prefixes

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Specify path prefixes to strip from endpoint paths in the index.

```python
http_index_ignore_prefixes = ['/internal', '/_proxy']
```

--------------------------------

### Add quick reference annotation to Flask route docstring

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

When using the 'qrefflask' directive without the 'autoquickref' option, routes intended for the quick reference table require a specific reStructuredText comment in their docstring. The format is '.. :quickref: [<resource>;] <short description>', where '<resource>' is optional and used for grouping.

```rst
.. :quickref: [<resource>;] <short description>
```

--------------------------------

### Reference an HTTP Method in RST

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use the http:method role to create a hyperlink to the specification of an HTTP verb.

```rst
It accepts :http:method:`post` only.
```

--------------------------------

### Qrefflask Directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Use the 'qrefflask' directive to generate a quick API reference table for Flask routes. It shares usage and options with 'autoflask' and includes an 'autoquickref' option.

```rst
.. qrefflask:: module:app

```

--------------------------------

### Describe JSON Parameters in Request Body

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use these roles to describe parameters within a JSON request body. Deprecated in favor of newer roles.

```rst
:jsonparam string title: the post title
:jsonparam string body: the post body
:jsonparam boolean sticky: whether it's sticky or not
```

--------------------------------

### autoflask Directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Directive for generating HTTP API references from Flask applications.

```APIDOC
## autoflask Directive

### Description
Generates RESTful HTTP API reference documentation from a Flask application's routing table.

### Directive

.. autoflask:: module:app

### Parameters

- **module:app** (string) - Required - The import name of the Flask application (e.g., `your.webapplication.module:app` or `your.webapplication.module:create_app(config='default.cfg')`).

### Options

- ``endpoints`` (list of strings)
  - Description: Specifies which endpoints to generate a reference for. If omitted or empty, all endpoints are documented.
  - Example: `:endpoints: user, post, friends`

- ``undoc-endpoints`` (list of strings)
  - Description: Excludes specified endpoints from the generated references.
  - Example: `:undoc-endpoints: admin, admin_login`

### Example Usage

.. sourcecode:: rst

   .. autoflask:: autoflask_sampleapp:app
      :undoc-static:

   .. autoflask:: yourwebapp:app
      :endpoints: user, post
      :undoc-endpoints: admin
```

--------------------------------

### Reference HTTP Headers

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Use the `:http:header:` role to reference HTTP request/response header fields. If the header is recognized, the text becomes a hyperlink to a web reference for that header. This role is part of the standard domain, not the HTTP domain.

```rst
Content-Type

```

--------------------------------

### Describe JSON Array Objects

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use these roles to describe objects within a JSON array in the response body. Similar to '<json' and '>json' but for array schemas.

```javascript
[{"id": "foo", "ok": true}, {"id": "bar", "error": "forbidden", "reason": "sorry"}]
```

```rst
:>jsonarr boolean ok: Operation status. Not present in case of error
:>jsonarr string id: Object ID
:>jsonarr string error: Error type
:>jsonarr string reason: Error reason
```

--------------------------------

### Document All Endpoints with Autotornado

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Omitting the `:endpoints:` option or providing an empty value documents all endpoints in the Tornado app.

```rst
.. autotornado:: yourwebapp:app
   :endpoints:
```

--------------------------------

### Describing JSON Array Objects

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Shows how to document the schema of objects contained within a JSON array in the response. This is useful for complex array structures.

```rst
:>jsonarr boolean ok: Operation status. Not present in case of error
:>jsonarr string id: Object ID
:>jsonarr string error: Error type
:>jsonarr string reason: Error reason
```

--------------------------------

### Reference HTTP Status Code

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use this role to create a hyperlink to a web reference for a given HTTP status code.

```rst
- :http:statuscode:`404`
- :http:statuscode:`200 OK`
```

--------------------------------

### HTTP Method Directives

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Directives used to define HTTP resource methods within Sphinx documentation.

```APIDOC
## HTTP Method Directives

### Description
Defines the HTTP method for a specific resource path. Supported methods include OPTIONS, HEAD, POST, GET, PUT, PATCH, DELETE, TRACE, COPY, and ANY.

### Methods
- http:options
- http:head
- http:post
- http:get
- http:put
- http:patch
- http:delete
- http:trace
- http:copy
- http:any

### Options
- **noindex**: Excludes the directive from the HTTP routing table.
- **deprecated**: Marks the method as deprecated in the HTTP routing table.
- **synopsis**: Adds a short description for the HTTP routing table.
- **addtoc**: Adds the API endpoint element to the page-level table of contents.
```

--------------------------------

### Describe Request Header Field

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use this role to document a specific field within an HTTP request header.

```rst
:reqheader Accept: the response content type depends on
                   :mailheader:`Accept` header
:reqheader Authorization: optional OAuth token to authenticate
```

--------------------------------

### User and Post Endpoints

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/http-routingtable.html

Endpoints for retrieving user information and specific posts.

```APIDOC
## GET /(?P<user>[a-z0-9]+)

### Description
Retrieves information for a specific user.

### Method
GET

### Endpoint
/(?P<user>[a-z0-9]+)

### Parameters
#### Path Parameters
- **user** (string) - Required - The user identifier.

## GET /(?P<user>[a-z0-9]+)/posts/(?P<post_id>[\d+]+)

### Description
Retrieves a specific post for a user.

### Method
GET

### Endpoint
/(?P<user>[a-z0-9]+)/posts/(?P<post_id>[\d+]+)

### Parameters
#### Path Parameters
- **user** (string) - Required - The user identifier.
- **post_id** (integer) - Required - The post identifier.
```

--------------------------------

### Describe Response Header Field

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use this role to document a specific field within an HTTP response header.

```rst
:resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
```

--------------------------------

### POST /posts/(int:post_id)

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Replies a comment to a specific post using form parameters and headers.

```APIDOC
## POST /posts/(int:post_id)

### Description
Replies a comment to the post.

### Method
POST

### Endpoint
/posts/(int:post_id)

### Parameters
#### Path Parameters
- **post_id** (int) - Required - post's unique id

#### Form Parameters
- **email** (string) - Required - author email address
- **body** (string) - Required - comment body

#### Request Headers
- **Accept** (string) - Required - the response content type depends on Accept header
- **Authorization** (string) - Optional - optional OAuth token to authenticate

### Response
#### Response Headers
- **Content-Type** (string) - this depends on Accept header of request

#### Status Codes
- **302** - and then redirects to GET /posts/(int:post_id)
- **400** - when form parameters are missing
```

--------------------------------

### POST /posts/(int:post_id)

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Replies a comment to a specific post.

```APIDOC
## POST /posts/(int:post_id)

### Description
Replies a comment to the post.

### Method
POST

### Endpoint
/posts/(int:post_id)

### Parameters
#### Path Parameters
- **post_id** (int) - Required - post's unique id

#### Request Body
- **email** (string) - Required - author email address
- **body** (string) - Required - comment body

#### Request Headers
- **Accept** - Required - the response content type depends on Accept header
- **Authorization** - Optional - optional OAuth token to authenticate

### Response
#### Response Headers
- **Content-Type** - This depends on Accept header of request

#### Status Codes
- **302** - and then redirects to /posts/(int:post_id)
- **400** - when form parameters are missing
```

--------------------------------

### Describe JSON Object Fields in Request Body

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use these roles to describe individual fields of a JSON object sent in the request body. Explicitly defines use-case for request/response.

```rst
:<json string title: the post title
:<json string body: the post body
:<json boolean sticky: whether it's sticky or not
```

--------------------------------

### Use autotornado directive

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Basic usage of the autotornado directive to document a Tornado application.

```rst
.. autotornado:: autotornado_sampleapp:app
```

--------------------------------

### Include specific modules in Flask API reference

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use the 'modules' option with the 'autoflask' directive to limit generated references to views within specified modules. This helps in organizing and filtering documentation.

```rst
.. autoflask:: yourwebapp:app
   :modules: yourwebapp.views.admin
```

--------------------------------

### Posts Management

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/http-routingtable.html

Endpoints for managing posts via post IDs.

```APIDOC
## GET /posts/(int:post_id)

### Description
Retrieves a post by ID.

### Method
GET

### Endpoint
/posts/(int:post_id)

## POST /posts/(int:post_id)

### Description
Updates or creates a post by ID.

### Method
POST

### Endpoint
/posts/(int:post_id)
```

--------------------------------

### Reference the Routing Table

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

To reference the generated routing table within your Sphinx documentation, use the ':ref:`routingtable`' directive. This was added in version 1.8.0.

```rst
:ref:`routingtable`
```

--------------------------------

### Describe JSON Object Fields in Response Body

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use these roles to describe individual fields of a JSON object returned in the response body. Explicitly defines use-case for request/response.

```rst
:>json boolean ok: Operation status
```

--------------------------------

### Document Specific Endpoints with Autotornado

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Use the `:endpoints:` option with `autotornado` to document only specified methods of RequestHandlers.

```rst
.. autotornado:: yourwebapp:app
   :endpoints: User.get, User.post, Friends.get
```

--------------------------------

### Order Flask endpoints by path

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

The 'order' option with the 'autoflask' directive can be set to 'path' to document all endpoints in a Flask app, ordered by their route paths. This requires the 'endpoints' option to be specified.

```rst
.. autoflask:: yourwebapp:app
   :endpoints:
   :order: path
```

--------------------------------

### HTTP Roles

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Custom roles provided by sphinxcontrib-httpdomain for referencing HTTP elements.

```APIDOC
## HTTP Roles

### Description
Custom roles for referencing HTTP status codes, methods, and headers.

### Roles

- `:http:statuscode:`
  - Description: References an HTTP status code (e.g., `:http:statuscode:`404`, `:http:statuscode:`200 OK`).
  - Example: `:http:statuscode:`404`

- `:http:method:`
  - Description: References an HTTP method (verb) and creates a hyperlink to a web reference.
  - Example: It accepts :http:method:`post` only.

- `:http:header:`
  - Description: References an HTTP request/response header field and creates a hyperlink to a web reference if known.
  - Known Headers: `Accept`, `Content-Type`, `Authorization`, etc. (See full list in documentation).
  - Example: :http:header:`Content-Type`
```

--------------------------------

### Reference HTTP Status Codes

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Use the `:http:statuscode:` role to reference HTTP status codes. It generates text like 'code Status Name' and creates a hyperlink to a web reference for the status code in HTML output. It can also reference specification sections.

```rst
- :http:statuscode:`404`
- :http:statuscode:`200 OK`

```

--------------------------------

### Set Short Name for HTTP Index

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/index.html

Configure the 'http_index_shortname' to define a short name for the index that will appear on every page. This was added in version 1.3.0.

```python
http_index_shortname = 'api'
```

--------------------------------

### Filter Endpoints in autoflask

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use the endpoints option to include specific view functions or document all endpoints.

```rst
.. autoflask:: yourwebapp:app
   :endpoints: user, post, friends
```

```rst
.. autoflask:: yourwebapp:app
   :endpoints:
```

--------------------------------

### Describe Response Status Code

Source: https://sphinxcontrib-httpdomain.readthedocs.io/en/latest/_sources/index.rst.txt

Use this role to document a response status code and its meaning.

```rst
:status 302: and then redirects to :http:get:`/posts/(int:post_id)`
:status 400: when form parameters are missing
```
Tokens:
Raw