Documentation de l'API de service web RESTful avec Sphinx [fermé]
Quelle est la meilleure façon de baliser les méthodes / URL pour un webservice RESTful utilisant ReST / Sphinx? Existe-t-il un domaine par défaut qui convient au marquage des URL avec leurs paramètres possibles, leurs méthodes HTTP, leurs en-têtes et leur contenu?
Quelque chose du genre:
.. 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
Est-ce que quelque chose comme ça existe déjà ou est-ce que l'une des extensions par défaut est utilisable, ou devrais-je en écrire une moi-même?
2 réponses
Le projetSphinx Contrib semble également avoir un paquetHTTP Domain pour documenter les API HTTP RESTful. Vous pouvez trouver sa documentation sur le site Python packages . Je ne peux pas parler de sa forme physique: je commence seulement à regarder dans Sphinx, et j'ai aussi besoin de documenter les API RESTful, et j'ai remarqué ce paquet contribué.
Comme il ne semble pas y avoir de solution existante, j'ai implémenté un domaine HTTP très simple que je peux utiliser pour marquer les méthodes 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)
Cela me permet de marquer des méthodes comme celle-ci et elles seront stylées un peu visuellement bien:
.. http:method:: GET /api/foo/bar/:id/:slug
:param id: An id
:param slug: A slug
Retrieve list of foobars matching given id.
Ce fut ma première incursion dans Sphinx et Python, donc cela devrait être considéré comme un code très rudimentaire. Si quelqu'un est intéressé à étoffer cela, veuillez fork ce projet sur Github!