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?

31
demandé sur deceze 2010-12-28 14:54:11

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

25
répondu Viktor Haag 2011-10-03 14:48:03

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!

18
répondu deceze 2011-01-19 08:52:56