rest - issue - neo4j http transactional endpoint

Documentación API de servicio web RESTful con Sphinx

Question

¿Cuál es la mejor manera de marcar métodos / URL para un servicio web RESTful utilizando ReST / Sphinx? ¿Existe un dominio predeterminado que sea adecuado para marcar URL con sus posibles parámetros, métodos HTTP, encabezados y contenido del cuerpo?

Algo como:

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

¿Ya existe algo como esto o es una de las extensiones predeterminadas que se pueden usar, o tendré que escribir una yo mismo?

Answer 1

Dado que no parece haber ninguna solución existente, he implementado un dominio HTTP muy simple que puedo usar para marcar los métodos 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)

Me permite marcar métodos como este y se diseñarán de forma visualmente agradable:

.. http:method:: GET /api/foo/bar/:id/:slug

   :param id: An id
   :param slug: A slug

   Retrieve list of foobars matching given id.

Esta fue mi primera incursión tanto en Sphinx como en Python, por lo que debería considerarse un código muy rudimentario. ¡Si alguien está interesado en dar cuerpo a esto, por favor bifurque este proyecto en Github !

Answer 2

El proyecto Sphinx Contrib también parece tener un paquete de dominio HTTP para documentar las API HTTP RESTful. Puede encontrar su documentación en el sitio de paquetes de Python . No puedo hablar de su estado físico: recién estoy comenzando a investigar Sphinx, y también tengo que documentar las API RESTful, y noté este paquete contribuido.