使用 Sphinx 的 RESTful Web 服务 API 文档 [已关闭]-解网

问：

闭。这个问题正在寻求有关书籍、工具、软件库等的建议。它不符合 Stack Overflow 准则。它目前不接受答案。

我们不允许向读者、工具、软件库等寻求推荐的问题。您可以编辑问题，以便用事实和引文来回答。

5年前关闭。

改进此问题

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

大致如下：

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

这样的东西是否已经存在，或者其中一个默认扩展可用，或者我必须自己编写一个？

REST 文档 python-sphinx

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 上分叉这个项目！

使用 Sphinx 的 RESTful Web 服务 API 文档 [已关闭]

RESTful web service API documentation with Sphinx [closed]

评论

评论

评论