`sphinxcontrib.httpdomain` — 用于记录HTTP API的Sphinx域¶

这个 contrib 扩展 sphinxcontrib.httpdomain 提供了一个用于描述HTTP API的Sphinx域。

参见

我们可能支持您的webapp依赖的Web框架的反射。请参阅以下内容 sphinxcontrib.autohttp 模块:

模块 sphinxcontrib.autohttp.flask: Flask 网络应用的反射。
模块 sphinxcontrib.autohttp.flaskqref: 快速参考渲染 sphinxcontrib.autohttp.flask
模块 sphinxcontrib.autohttp.bottle: Bottle webapps 的反射。
模块 sphinxcontrib.autohttp.tornado: Tornado webapps 的反射。

为了使用它，将 sphinxcontrib.httpdomain 添加到 Sphinx 配置文件(conf.py)的 extensions 列表中:

extensions = ['sphinxcontrib.httpdomain']

附加配置¶

http_headers_ignore_prefixes

在严格模式下应忽略的HTTP头前缀列表:

http_headers_ignore_prefixes = ['X-']

1.4.0 新版功能.

1.5.0 版后已移除: 严格模式不再警告非标准标头前缀。

http_index_ignore_prefixes

通过给定的前缀列表从端点路径中剥离前导段:

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

1.3.0 新版功能.

http_index_shortname

将出现在每页上的索引的简称:

http_index_shortname = 'api'

1.3.0 新版功能.

http_index_localname

索引页面上使用的完整索引名称:

http_index_localname = "My Project HTTP API"

1.3.0 新版功能.

http_strict_mode

当 True (默认)在状态代码，方法和标题看起来非标准时发出构建错误:

http_strict_mode = True

1.4.0 新版功能.

基本用法¶

提供了几个 directives 来描述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 /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 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 Accept header

Reqheader Authorization

optional OAuth token to authenticate

Resheader Content-Type

this depends on Accept header of request

Statuscode 200

no error

Statuscode 404

there’s no user

当然， roles 也可以引用指令。例如:

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

将渲染像:

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

指令¶

.. http:options:: path¶: 描述HTTP资源的 OPTIONS 方法。它也可以通过以下方式引用 http:options 角色。

.. http:head:: path¶: 描述HTTP资源的 HEAD 方法。它也可以通过以下方式引用 http:head 角色。

.. http:post:: path¶: 描述HTTP资源的 POST 方法。它也可以通过以下方式引用 http:post 角色。

.. http:get:: path¶: 描述HTTP资源的 GET 方法。它也可以通过以下方式引用 http:get 角色。

.. http:put:: path¶: 描述HTTP资源的 PUT 方法。它也可以通过以下方式引用 http:put 角色。

.. http:patch:: path¶: 描述HTTP资源的 PATCH 方法。它也可以通过以下方式引用 http:patch 角色。

.. http:delete:: path¶: 描述HTTP资源的 DELETE 方法。它也可以通过以下方式引用 http:delete 角色。

.. http:trace:: path¶: 描述HTTP资源的 TRACE 方法。它也可以通过以下方式引用 http:trace 角色。

.. http:copy:: path¶: 描述HTTP资源的 :http:method:COPY` 方法。它也可以通过以下方式引用 http:copy 角色。

1.3.0 新版功能.

.. http:any:: path¶: 描述一个HTTP资源，它接受请求 any 方法。对于请求资源将请求代理到保留原始请求上下文的某个其他位置的情况很有用。它也可以通过以下方式引用 http:any 角色。

1.3.0 新版功能.

选项¶

1.3.0 新版功能.

此外，您可以为指令指定自定义选项:

noindex

从HTTP路由表中排除特定指令。

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

deprecated

在HTTP路由表中将该方法标记为已弃用。

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

synopsis

添加HTTP路由表的简短描述。

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

资源字段¶

内部HTTP资源描述指令如 get ，带有这些字段的reStructuredText字段列表可以很好地识别和格式化:

param, parameter, arg, argument

URL参数的描述。

queryparameter, queryparam, qparam, query

请求查询字符串传递的参数说明。

它可以选择键入，但所有查询参数都有明显的字符串类型。但是如果有它的约定它是有用的。

在 1.1.9 版更改: 它可以是打字的:

: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

由请求内容体传递的参数的描述，编码在 application/x-www-form-urlencoded 或 multipart/form-data 。

jsonparameter, jsonparam, json

请求内容体传递的参数的描述，编码在 application/json 。

1.3.0 版后已移除: 使用 reqjsonobj/reqjson/<jsonobj/<json 和 reqjsonarr/<jsonarr 代替.

1.1.8 新版功能.

在 1.1.9 版更改: 它可以是打字的:

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

reqjsonobj, reqjson, <jsonobj, <json

请求体传递的JSON对象的单个字段的描述，编码在 application/json 。与 json 的主要区别在于明确定义了所描述对象的用例(请求/响应)。

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

1.3.0 新版功能.

resjsonobj, resjson, >jsonobj, >json

与响应体一起返回的JSON对象的单个字段的描述，编码在 application/json 。

:>json boolean ok: Operation status

1.3.0 新版功能.

reqjsonarr, <jsonarr resjsonarr, >jsonarr

类似于 <json 和 > json ，但用于描述返回数组内的对象模式。

假设响应包含以下数据:
[{"id": "foo", "ok": true}, {"id": "bar", "error": "forbidden", "reason": "sorry"}]
然后我们可以用以下方式描述它:
:>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
1.3.0 新版功能.

:>json boolean status: Operation status

requestheader, reqheader, >header: 请求标头字段的描述。

1.1.9 新版功能.
responseheader, resheader, <header: 响应头字段的描述。

1.1.9 新版功能.
statuscode, status, code: 响应状态代码的描述。

例如:

.. 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

   (...)

它会像这样渲染:

POST /posts/(int: post_id)¶

Replies a comment to the post.

参数

post_id (int) – post’s unique id

Form email

author email address

Form body

comment body

Reqheader Accept

the response content type depends on Accept header

Reqheader Authorization

optional OAuth token to authenticate

Resheader Content-Type

this depends on Accept header of request

Status 302

and then redirects to GET /posts/(int:post_id)

Status 400

when form parameters are missing

GET /posts/(int: post_id)¶

Fetches the post

(…)

角色¶

:http:options:¶: 指的是 http:options 指令。

:http:head:¶: 指的是 http:head 指令。

:http:post:¶: 指的是 http:post 指令。

:http:get:¶: 指的是 http:get 指令。

:http:put:¶: 指的是 http:put 指令。

:http:patch:¶: 指的是 http:patch 指令。

:http:delete:¶: 指的是 http:delete 指令。

:http:trace:¶: 指的是 http:trace 指令。

:http:copy:¶: 指的是 http:copy 指令。

:http:any:¶: 指的是 http:any 指令。

:http:statuscode:¶

对HTTP状态代码的引用。生成文本 “code Status Name” ;在HTML输出中，此文本是指向指定状态代码的Web引用的超链接。

例如:

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

将呈现为:

404 Not Found

200 OK

在 1.3.0 版更改: 它成为提供规范部分的参考。

:http:method:¶

对HTTP方法的引用(也称为 verb )。在HTML输出中，此文本是指向指定HTTP方法的Web引用的超链接。

例如:

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

它会像这样渲染:

它只接受 POST 。

:mimetype:¶: 确切地说，它不属于HTTP域，而是属于标准域。它指的是MIME类型，如 text/html 。

:mailheader:¶: 1.3.0 版后已移除: 使用 http:header 代替。

:http:header:¶

类似于 mimetype 角色，它不属于HTTP域，而属于标准域。它引用HTTP请求/响应头字段，如 Content-Type 。

如果HTTP标头已知，则文本是指向指定标头的Web引用的超链接。

已知的HTTP标头:

1.3.0 新版功能.

在 1.5.0 版更改: 不再针对无法识别的标头发出警告

`sphinxcontrib.autohttp.flask` — 从Flask应用程序导出API参考¶

1.1 新版功能.

它从 Flask 应用程序的路由表生成RESTful HTTP API参考文档，类似于 sphinx.ext.autodoc 。

为了使用它，将 sphinxcontrib.autohttp.flask 添加到 extensions 列表中的Sphinx配置(conf.py)文件:

extensions = ['sphinxcontrib.autohttp.flask']

例如:

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

将呈现为:

.. autoflask:: module:app¶

1.1 新版功能.

从Flask应用程序生成HTTP API引用。它需要一个导入名称，比如:

your.webapplication.module:app

冒号字符(:)分隔模块路径和应用程序变量。后期部分可能更复杂:

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

当从工厂函数(create_app(), 在上面的例子中)创建Flask应用程序时，它很有用。

它也需要几个标志选项。

endpoints

端点生成引用。

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

将记录 user() ， post() ，和 friends() 查看函数，以及

.. autoflask:: yourwebapp:app
   :endpoints:

将记录烧瓶应用程序中的所有端点。

为了兼容性，省略此选项将产生与上面相同的效果。

1.1.8 新版功能.

undoc-endpoints

从生成的引用中排除指定的端点。

例如:

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

将排除 admin() ， admin_login() 查看函数。

注解

值得注意的是，应用于蓝图的端点名称以蓝图的名称为前缀(例如 blueprint.endpoint )。

注解

虽然 sphinx.ext.autodoc 扩展的 undoc-members 标志包含没有 docstrings 的成员，但 undoc-endpoints 选项与docstrings无关。它只是排除了指定的端点。

blueprints

仅在生成的引用中包含指定的蓝图。

1.1.9 新版功能.

undoc-blueprints

从生成的引用中排除指定的蓝图。

1.1.8 新版功能.

modules

仅在生成的引用中包含指定的视图模块。

例如:

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

将仅包含 yourwebapp.views.admin 模块中的视图

1.5.0 新版功能.

undoc-modules

从生成的引用中排除指定的视图模块。

1.5.0 新版功能.

undoc-static

排除提供静态文件的视图函数，默认情况下包含在Flask中。

order

确定列出端点的顺序。目前只支持 path 。

例如:

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

将记录烧瓶应用中的所有端点，按其路径路径排序。

1.5.0 新版功能.

groupby

确定分组路径的策略。目前只支持 view 。指定它将按视图函数对路径进行分组。

1.6.0 新版功能.

include-empty-docstring

默认情况下排除没有 docstring (__doc__) 的视图函数。如果给出了这个标志选项，它们也会被包括在内。

1.1.2 新版功能.

`sphinxcontrib.autohttp.flaskqref` — Flask app的快速API参考¶

1.5.0 新版功能.

这将为以下生成的路径文档生成一个快速API参考表 sphinxcontrib.autohttp.flask

要使用它，两者 sphinxcontrib.autohttp.flask 和 sphinxcontrib.autohttp.flaskqref 需要添加到配置(conf.py)文件的扩展名中:

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

.. qrefflask:: module:app¶: 1.5.0 新版功能.

从Flask应用程序生成HTTP API引用，并将它们放在带有快速引用链接的列表表中。用法和选项与 sphinxcontrib.autohttp.flask 相同，增加了 autoquickref 选项。

基本用法¶

您通常会将快速参考表放在docco顶部附近并使用 .. autoflask:: 进一步向下。

除非使用 autoquickref 选项，否则要包含在快速参考表中的路由需要将以下第一条注释添加到其文档字符串中:

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

<resource> 是可选的，如果使用分号，则将其与 <short description> 分开。该表按 <resource> 分组和排序。

<resource>: 这是操作的资源名称。对于许多操作，名称可能相同，并且可以将这些组合在一起。
<short description>: 简要说明操作的作用。

如果使用 autoquickref 选项，则所有路径都必须在蓝图内。 <resource> 将被设置为蓝图的名称， <short description> 将被设置为 docstring 的第一行。

例如:

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

    .. :quickref: User; Get Profile Page

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

快速参考表定义为:

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

使用带有 .. :quickref: 注释的 autoflask_sampleapp ，将其呈现为:

`sphinxcontrib.autohttp.bottle` — 从Bottle应用程序导出API参考¶

它从 Bottle 应用程序的路由表生成RESTful HTTP API参考文档，类似于 sphinx.ext.autodoc 。

为了使用它，将 sphinxcontrib.autohttp.bottle 添加到 extensions 列表中的Sphinx配置(conf.py)文件:

extensions = ['sphinxcontrib.autohttp.bottle']

例如:

.. autobottle:: autobottle_sampleapp:app

将呈现为:

.. autobottle:: module:app¶

从Bottle应用程序生成HTTP API引用。它需要一个导入名称，比如:

your.webapplication.module:app

冒号字符(:)分隔模块路径和应用程序变量。后期部分可能更复杂:

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

从工厂函数(create_app(), 在上例中)创建Bottle应用程序时，它很有用。

它也需要几个标志选项。

endpoints

端点生成引用。

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

将记录 user() ， post() ，和 friends() 查看函数，以及

.. autobottle:: yourwebapp:app
   :endpoints:

将记录瓶子应用程序中的所有端点。

为了兼容性，省略此选项将产生与上面相同的效果。

undoc-endpoints

从生成的引用中排除指定的端点。

例如:

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

将排除 admin() ， admin_login() 查看函数。

注解

虽然 sphinx.ext.autodoc 扩展的 undoc-members 标志包含没有 docstrings 的成员，但 undoc-endpoints 选项与docstrings无关。它只是排除了指定的端点。

include-empty-docstring

默认情况下排除没有 docstring (__doc__) 的视图函数。如果给出了这个标志选项，它们也会被包括在内。

`sphinxcontrib.autohttp.tornado` — 从Tornado应用程序导出API参考¶

它从 Tornado 应用程序的路由表生成RESTful HTTP API参考文档，类似于 sphinx.ext.autodoc 。

为了使用它，将 sphinxcontrib.autohttp.tornado 添加到 extensions 列表中的Sphinx配置(conf.py)文件:

extensions = ['sphinxcontrib.autohttp.tornado']

例如:

.. autotornado:: autotornado_sampleapp:app

将呈现为:

.. autotornado:: module:app¶

从Tornado应用程序生成HTTP API引用。它需要一个导入名称，比如:

your.webapplication.module:app

冒号字符(:)分隔模块路径和应用程序变量。

它也需要几个标志选项。

endpoints

端点生成引用。

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

将记录 get() 和 post() 方法 User RequestHandler 和 get() 方法 Friend RequestHandler ，而

.. autotornado:: yourwebapp:app
   :endpoints:

将记录龙卷风应用程序中的所有端点。

为了兼容性，省略此选项将产生与上面相同的效果。

undoc-endpoints

从生成的引用中排除指定的端点。

例如:

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

将排除 admin() ， admin_login() 查看函数。

注解

虽然 sphinx.ext.autodoc 扩展的 undoc-members 标志包含没有 docstrings 的成员，但 undoc-endpoints 选项与docstrings无关。它只是排除了指定的端点。

include-empty-docstring

默认情况下排除没有 docstring (__doc__) 的视图函数。如果给出了这个标志选项，它们也会被包括在内。

作者和许可证¶

sphinxcontrib.httpdomain 和 sphinxcontrib.autohttp ，部分 sphinxcontrib ，由 Hong Minhee 编写，并在BSD许可下发布。

源代码在 httpdomain 存储库中的 sphinx-contrib project 下维护

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

目录

上一个主题

下一个主题

本页

`sphinxcontrib.httpdomain` — 用于记录HTTP API的Sphinx域¶

附加配置¶

基本用法¶

指令¶

选项¶

资源字段¶

角色¶

`sphinxcontrib.autohttp.flask` — 从Flask应用程序导出API参考¶

`sphinxcontrib.autohttp.flaskqref` — Flask app的快速API参考¶

基本用法¶

`sphinxcontrib.autohttp.bottle` — 从Bottle应用程序导出API参考¶

`sphinxcontrib.autohttp.tornado` — 从Tornado应用程序导出API参考¶

作者和许可证¶

sphinxcontrib.httpdomain — 用于记录HTTP API的Sphinx域¶

附加配置¶

基本用法¶

指令¶

选项¶

资源字段¶

角色¶

sphinxcontrib.autohttp.flask — 从Flask应用程序导出API参考¶

sphinxcontrib.autohttp.flaskqref — Flask app的快速API参考¶

基本用法¶

sphinxcontrib.autohttp.bottle — 从Bottle应用程序导出API参考¶

sphinxcontrib.autohttp.tornado — 从Tornado应用程序导出API参考¶

作者和许可证¶

`sphinxcontrib.httpdomain` — 用于记录HTTP API的Sphinx域¶

`sphinxcontrib.autohttp.flask` — 从Flask应用程序导出API参考¶

`sphinxcontrib.autohttp.flaskqref` — Flask app的快速API参考¶

`sphinxcontrib.autohttp.bottle` — 从Bottle应用程序导出API参考¶

`sphinxcontrib.autohttp.tornado` — 从Tornado应用程序导出API参考¶