Documentation de l'API de service Web RESTful avec Sphinx

Question

Quel est le meilleur moyen de baliser les méthodes / URL pour un service Web RESTful utilisant ReST / Sphinx? Existe-t-il un domaine par défaut approprié pour marquer les URL avec leurs paramètres possibles, les méthodes HTTP, les en-têtes et le contenu du corps?

Quelque chose dans le genre de:

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

Existe-t-il déjà quelque chose comme ceci ou l'une des extensions par défaut est-elle utilisable ou devrai-je en écrire une moi-même?

Answer 1

Le projet Sphinx Contrib semble également disposer d'un package de domaine HTTP permettant de documenter les API HTTP RESTful. Vous pouvez trouver sa documentation sur le site des packages Python . Je ne peux pas vous parler de son aptitude: je commence tout juste à examiner Sphinx et j'ai également besoin de documenter les API RESTful, et j'ai remarqué ce paquet contributif.

Answer 2

Depuis il ne semble pas être une solution existante, j'ai mis en place un très simple HTTP domaine que je peux utiliser pour marquer les méthodes de l'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)

Il me permet de marquer des méthodes de ce genre et ils vont être de style 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.

C'était ma première incursion dans les deux Sphinx et Python, donc cela devrait être considéré comme très rudimentaire code. Si quelqu'un est intéressé pour étoffer ce, s'il vous plaît fourche de ce projet sur Github!