31

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

このようなものは既に存在していますか、使用可能なデフォルトの拡張機能の 1 つですか、それとも自分で作成する必要がありますか?

4

2 に答える 2

25

Sphinx Contribプロジェクトにも、RESTful HTTP API を文書化するための HTTP Domain パッケージがあるようです。そのドキュメントは、Python パッケージサイトにあります。その適合性について話すことはできません: Sphinx を調べ始めたばかりで、RESTful API も文書化する必要があり、この寄稿パッケージに気付きました。

于 2011-10-03T14:48:03.987 に答える
18

既存のソリューションがないように見えるため、API メソッドのマークアップに使用できる非常に単純な HTTP ドメインを実装しました。

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 でフォークしてください。

于 2011-01-19T07:51:35.407 に答える