स्फिंक्स

Question

के साथ रीस्टफुल वेब सेवा एपीआई दस्तावेज रीस्ट/स्फिंक्स का उपयोग कर एक विश्वसनीय webservice के लिए विधियों/यूआरएल को मार्कअप करने का सबसे अच्छा तरीका क्या है? क्या कोई डिफ़ॉल्ट डोमेन है जो यूआरएल को उनके संभावित पैरामीटर, 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 

कुछ इस तरह पहले से ही मौजूद है या प्रयोग करने योग्य डिफ़ॉल्ट एक्सटेंशन में से एक है है, या मैं एक अपने आप को लिखने के लिए करना होगा?

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) 

यह मुझे इस तरह के तरीकों को चिह्नित करने के लिए अनुमति देता है:

Answer 1

Sphinx Contrib प्रोजेक्ट में रीस्टफुल HTTP एपीआई दस्तावेज करने के लिए HTTP डोमेन पैकेज भी प्रतीत होता है। आप Python packages साइट पर इसका दस्तावेज़ीकरण पा सकते हैं। मैं अपनी फिटनेस से बात नहीं कर सकता: मैं केवल स्फिंक्स को देखना शुरू कर रहा हूं, और मुझे रीस्टफुल एपीआई को भी दस्तावेज करने की आवश्यकता है, और इस योगदान पैकेज को देखा।

Answer 2

के बाद से वहाँ किसी भी मौजूदा समाधान होने के लिए प्रकट नहीं होता है, मैं एक बहुत ही सरल HTTP डोमेन है कि मैं एपीआई तरीकों को चिह्नित करने के लिए उपयोग कर सकते लागू कर दिया है और वे कुछ हद तक नेत्रहीन अच्छी तरह से स्टाइल जाएगा:

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

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

    Retrieve list of foobars matching given id. 

यह मेरी दोनों स्फिंक्स और अजगर में प्रथम प्रयास था, तो यह बहुत ही मौलिक कोड माना जाना चाहिए। अगर कोई इसे बाहर निकालने में रूचि रखता है, तो कृपया fork this project on Github!