Automatically document my REST API

Question

I am trying to create documentation automatically from the code for all the URLs supported by my application. We are using completely client side MVC, hence each URL that is supported is essentially a REST API for the UI. Is there a easy way to generate the documentation from these URLs?

I wrote this small module as of now, but I am looking for better ways then this. I don't want to re-invent the wheel if something similar already exists.

UPDATE: Note the intent is to provide a public documentation for the consumers of the website, not for internal consumption. In this regard, for each URL we need to document: - what is the response, - which parameters are accepted, - if the URL responds to GET/POST or both, etc.

Certain URLs like (^$) that simply redirect to home page should not be documented, so I will need some exclusion mechanism as well.

from django.core.management.base import BaseCommand
from django.conf import settings


class Command(BaseCommand):
''' Generates documentation for the URLs.  For each URL includes the documentation from
the callback implementing the URL and prints the default arguments along with the URL pattern and name'''

    def handle(self, *args, **options):
        url_module = None
        exec 'import '+settings.ROOT_URLCONF+'; url_module='+settings.ROOT_URLCONF
        doc = file('doc.html','w')
        doc.write("<table border=1 cellspacing=0 cellpadding=5>")
        doc.write("<tr><th>URL Pattern<th>Name<th>Documentation<th>Parameters")
        for x in url_module.urlpatterns:
            doc.write("<tr>")
            doc.write("<td>")
            doc.write(x._regex)
            doc.write("<td>")
            doc.write(str(x.name))
            try:
                documentation = str(x.callback.__doc__)
                doc.write("<td><pre>")
                doc.write(documentation)
                doc.write("</pre>")
            except:
                doc.write("<td> Unable to find module")
            doc.write("<td>")
            doc.write(str(x.default_args))
        doc.write("</table>")
        doc.close()

Answer 1

You can traverse the URL patterns from the root module and introspect the view function objects to get the documentation data like you did, but I'd rather be rendering it through a template to compile the document.

I'd suggest, though, that you employ Sphinx. You'll probably need to document more than just your endpoints (terms of use, privacy policy, authentication, yadda yadda) and you can write your own extensions that'll expose a directive you can call in one document to do exactly what you've been doing here.

Or you could simply avoid engineer this altogether: manage your Sphinx docs by hand, create a Github repository and host the documentation on https://readthedocs.org/!

Answer 2

Just a Final Update in case anyone is interested.

We ended up using the code snippet I have for internal purposes. We have decided to venture into Sphinx and use that, when we are creating the developer guide at the end of the project, when we are ready for public beta, since it requires some time and investment for learning, logistics etc.