Home

Tornado-swagger scan docstring in your handlers and classes with special mark (register_swagger_model) and export to single swagger file. Optionally you can start swagger-ui at same host.

HowTo

Add setup_swagger(routes) for start swagger-ui and specification extraction

from tornado_swagger.setup import setup_swagger


class Application(tornado.web.Application):
    _routes = [
        tornado.web.url(r'/api/posts', PostsHandler),
        tornado.web.url(r'/api/posts/(\w+)', PostsDetailsHandler),
    ]

    def __init__(self):
        setup_swagger(self._routes)
        super(Application, self).__init__(self._routes)

Define handler specification

class PostsDetailsHandler(tornado.web.RequestHandler):
    def get(self, posts_id):
        """
        ---
        # write swagger specification here
        """

Define model specification

from tornado_swagger.model import register_swagger_model


@register_swagger_model
class PostModel:
    """
    ---
    type: object
    description: Post model representation
    properties:
        id:
            type: integer
            format: int64
        title:
            type: string
        text:
            type: string
        is_visible:
            type: boolean
            default: true
    """

Export swagger specification file without serving swagger-ui

from tornado_swagger.setup import export_swagger


swagger_specification = export_swagger(routes)

Example

class PostsDetailsHandler(tornado.web.RequestHandler):
    def get(self, posts_id):
        """
        ---
        tags:
        - Posts
        summary: Get posts details
        description: posts full version
        produces:
        - application/json
        parameters:
        -   name: posts_id
            in: path
            description: ID of post to return
            required: true
            type: string
        responses:
            200:
              description: list of posts
              schema:
                $ref: '#/definitions/PostModel'
        """