GitHub - singalen/tornado-rest-swagger: Swagger Documentation Generator for the Tornado Web Framework

singalen / tornado-rest-swagger Public

forked from flier/tornado-rest-swagger

Notifications You must be signed in to change notification settings
Fork 0
Star 0

Swagger Documentation Generator for the Tornado Web Framework

Notifications

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
src/tornado_rest_swagger		src/tornado_rest_swagger
.gitignore		.gitignore
README		README
ez_setup.py		ez_setup.py
requirements.txt		requirements.txt
setup.py		setup.py

Repository files navigation

Installing
----------

1. ??? Install Swagger-UI libraries into /assets/lib/
2. If you're initializing your Tornado application like

    class MyApplication(tornado.web.Application):
        def __init__(self):
            handlers = [
                (r'/user/', UserHandler),
                ...
            ]
            settings = dict(debug="True")
            tornado.web.Application.__init__(self, handlers, **settings)

then add Swagger handlers like

    swagger_handlers = tornado_rest_swagger.urls.handle_apidoc_urls(r'/swagger', **settings)
    tornado.web.Application.__init__(self, handlers + swagger_handlers, **settings)

Documenting API methods
-----------------------

Write a docstrting in [epytext](http://epydoc.sourceforge.net/epytext.html) format like:

    """
    Updates a user.

    @type user: my.package.models.UserModel
    @param user: The user JSON to be updated
    @rtype: my.package.models.UserModel

    """
Full tag list is:
* @paramtype <name>: <http-parameter-type> (convention: defaults to 'path', could be 'query'. I can also think of 'body' and 'header'; might be arbitrary string).
* @type <name>: <dataType> (where dataType is a FQN like my.package.models.DeviceModel or a str/int/bool)
* @param <name>: <description>
    bug: @type and @paramtype must go BEFORE a @param.
* @rtype <return type>
* @raisetype <error code>: <return type with the given code> (Apparently not supported by swagger-ui yet)
* @raise <error code>: <error reason>
    bug: @raisetype must go BEFORE a @raise.
    note: @return is a synonym of @raise for now.
* @note: <note>
* @summary: <summary>

bug: Each tag can have an argument and a body:
    @raise <argument>: <body>.
If a tag has no body, it still must have a semicolon ':', otherwise it won't be seen by Swagger. Like:
    @raise 200:

Missing: there's no way to describe an array of anything as a return type.

TODO: in-place model declaration for @type/@rtype