使用Sphinx的RESTful web服务API文档

使用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

---

类似的东西是否已经存在，或者是可用的默认扩展之一，或者我必须自己编写一个吗？

由于似乎没有任何现有的解决方案，我实现了一个非常简单的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，因此这应该被认为是非常基本的代码。如果有人对充实这一点感兴趣，请

该项目似乎还有一个用于记录RESTful HTTP API的HTTP域包。你可以在网站上找到它的文档。我不能谈论它的适用性：我才刚刚开始研究Sphinx，我还需要记录RESTful API，并注意到这个有贡献的包。

您找到了解决这个问题的方法吗？面对同样的“问题”：@Henrik See。太好了！谢谢你应该在标题中添加Restful一词，以便在这个主题上获得更高的google pagerank:）我可以这样做，但我不喜欢把好问题弄得一团糟。@Henrik说得好。：）我正在考虑把这个放到Github上，以便进行一些协作开发。你觉得呢？如果一切都结束了不会伤害任何人；）我今天从python包索引安装了它，但它根本不起作用。引发了此异常：TypeError:\uuuu init\uuuuuuu（）获取了意外的关键字参数“can\u collapse”+1。我今天尝试了这个扩展，发现它是一个非常好的开始。它还附带了一个模块，可以扫描Flask应用程序的路由表以获取文档，就像autodoc一样。（我还没有试过那个部分。）将这个标记为已接受，因为我认为它是维护更好的包。我的版本现在基本上已经被放弃了（尽管它确实可以正常工作）。我现在可以评论说，我们已经在生产中使用Sphinx（带有HTTP域包）一年了，它做得很好。我在本地做了一些修改，以适应我们的特殊需要，但总的来说，我对结果非常满意。注意：sphinxcontrib.autohttp.tornado仅适用于Python 2.x，因为它导入了StringIO。@protener，据我所知，这不是我指的扩展包：我指的是

sphinxcontrib httpdomain

。