RESTful WebサービスAPIドキュメント（スフィンクス

Question

）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つを自分で記述する必要がありますでしょうか？

Answer 1

Sphinx Contribプロジェクトには、RESTful HTTP APIを文書化するための HTTPドメインパッケージがあるようです。そのドキュメントはPython packagesサイトでご覧いただけます。 Sphinxを調べ始めたばかりで、RESTfulなAPIも文書化する必要があり、この寄贈されたパッケージに気付きました。

Answer 2

任意の既存のソリューションがあるように表示されませんので、私は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. 

これはスフィンクスとPythonの両方への私の最初の進出だったので、これは非常に初歩的なコードを考慮すべきです。もし誰かがこれを解き放つことに興味があれば、fork this project on Githubをください！