使用Sphinx撰写RESTful Web服务API文档

Question

在使用 ReST/Sphinx 标记 RESTful web 服务的方法/URL 时，最佳做法是什么？是否有一个默认的域适合标记 URL 的可能参数、HTTP 方法、头和正文内容？

类似以下方式：

.. rest:method:: GET /api/foo

   :param bar: A valid bar
   :extension: json or xml

   Retrieve foos for the given parameters. E.g.::

      GET /api/foo.json?bar=baz

类似这样的东西已经存在了吗？或者可以使用默认的扩展之一吗？还是我必须自己编写一个？

- deceze

---

你找到解决这个问题的方法了吗？我也遇到了同样的“问题” :) - Henrik P. Hessel

@Henrik 请查看下面的答案：（https://dev59.com/zm855IYBdhLWcg3wFAHy#4732927）。 - deceze

Answer 1

Sphinx Contrib 项目似乎还有一个适用于文档化 RESTful HTTP API 的 HTTP Domain 包。 您可以在 Python packages 网站上找到它的文档。 我无法确定其适用性：我刚开始研究 Sphinx，并且我需要文档化 RESTful API，然后注意到这个贡献的包。

- Viktor Haag

---

我可以评论一下，我们已经在生产中使用Sphinx（与_HTTP Domain_软件包一起），效果非常好。我对结果感到非常满意，虽然为了满足我们的特定需求，我做了一些本地化修改。 - Viktor Haag

注意：sphinxcontrib.autohttp.tornado仅适用于Python 2.x，因为它导入了StringIO。 - proteneer

据我所知，@proteneer，这不是我所指的扩展包：我指的是sphinxcontrib-httpdomain。 - Viktor Haag

httpdomain有适用于tornado/flask/bottle等的扩展。 - proteneer

啊！我明白了。这对我来说不是很清楚，而且我也没有使用这个功能，所以不知道它的问题。 - Viktor Haag

Answer 2

由于似乎没有任何现有的解决方案，所以我实现了一个非常简单的HTTP域，可以用来标记API方法：

import re

from docutils import nodes

from sphinx import addnodes
from sphinx.locale import l_, _
from sphinx.domains import Domain, ObjType
from sphinx.directives import ObjectDescription


http_method_sig_re = re.compile(r'^(GET|POST|PUT|DELETE)?\s?(\S+)(.*)$')

class HTTPMethod(ObjectDescription):

    def handle_signature(self, sig, signode):
        m = http_method_sig_re.match(sig)
        if m is None:
            raise ValueError

        verb, url, query = m.groups()
        if verb is None:
            verb = 'GET'

        signode += addnodes.desc_addname(verb, verb)
        signode += addnodes.desc_name(url, url)

        if query:
            params = query.strip().split()
            for param in params:
                signode += addnodes.desc_optional(param, param)

        return url


class HTTPDomain(Domain):
    """HTTP language domain."""
    name = 'http'
    label = 'HTTP'
    object_types = {
        'method':    ObjType(l_('method'),    'method')
    }
    directives = {
        'method':       HTTPMethod
    }

def setup(app):
    app.add_domain(HTTPDomain)

它允许我对方法进行标记，就像这样，它们将被视觉上美观地呈现：

.. http:method:: GET /api/foo/bar/:id/:slug

   :param id: An id
   :param slug: A slug

   Retrieve list of foobars matching given id.

这是我第一次尝试使用Sphinx和Python，所以这段代码应该被认为是非常基础的。如果有人有兴趣拓展它，请在Github上fork这个项目！

- deceze

---

太好了！谢谢！你应该在标题中加入“Restful”这个术语，以获得更高的谷歌页面排名 :) 我可以做到，但我不想破坏好问题。 - Henrik P. Hessel

@Henrik 很好的建议。 :) 我正在考虑将其上传到 Github 上，以便进行一些协作开发。你觉得怎么样？ - deceze

如果它在Github上结束，就不会伤害任何人 ;) - Henrik P. Hessel

我今天从Python软件包索引安装了这个，但它根本不起作用。抛出了以下异常：TypeError: init() got an unexpected keyword argument 'can_collapse'。 - ʇsәɹoɈ