How to generate swagger specification file (json) from python using annotations in code?

Question

Problem statement: I want to automate the generation of machine and human readable specifications for JSON APIs so anyone can visualize and interact with our API.
One of the feasible solution is to use OpenAPISpecification (fka swagger). I was not able to find a comprehensible guide to use swagger particularly with tornado, so my questions are:

1. How can I auto generate swagger specification file from annotations in python code?
2. I'm also using JSON schemas for input validation, how can I integrate these with swagger specification.

My API is written in python 2.7.11 with tornado 4.3. Please do suggest if you have any other suggestion than using swagger too.

Update: Apispec is an interesting start but it cannot be used with JSON schemas as of now, so doesn't answer my question entirely.

Answer 1

we recently had this requirement at work. We made our own generator which generates OpenAPI 3.0 api spec from Google style docstrings. You just need to decorate handlers and model classes. For more info: https://pypi.org/project/tornado-swirl/ -- still a work in progress though but we are actively working on it.

import tornado.web
import tornado_swirl as swirl

@swirl.restapi('/item/(?P<itemid>\d+)')
class ItemHandler(tornado.web.RequestHandler):

    def get(self, itemid):
        """Get Item data.

        Gets Item data from database.

        Path Parameter:
            itemid (int) -- The item id
        """
        pass

@swirl.schema
class User(object):
    """This is the user class

    Your usual long description.

    Properties:
        name (string) -- required.  Name of user
        age (int) -- Age of user

    """
    pass



def make_app():
    return swirl.Application(swirl.api_routes())

if __name__ == "__main__":
    app = make_app()
    app.listen(8888)
    tornado.ioloop.IOLoop.current().start()