Документация API веб-сервиса RESTful с Sphinx
Какой лучший способ разметки методов/URL-адресов для веб-службы RESTful с использованием ReST/Sphinx? Существует ли домен по умолчанию, подходящий для разметки 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
Что-то вроде этого уже существует или является одним из используемых по умолчанию расширений, или я должен сам написать его?
Ответы
Ответ 1
В проекте Sphinx Contrib также есть пакет HTTP-домена для документирования HTTP-API RESTful. Вы можете найти свою документацию на сайте Python packages. Я не могу говорить о его пригодности: я только начинаю заглядывать в Sphinx, и мне также нужно документировать API RESTful, и заметил этот пакет.
Ответ 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!