如何使用代码中的注释从python生成swagger规范文件(json)？

Question

问题陈述:我想自动生成JSON API的机器和人类可读规范,这样任何人都可以看到我们的API并与之交互.
其中一个可行的解决方案是使用OpenAPISpecification(fka swagger).我无法找到一个可以理解的指南,特别是龙卷风使用招摇,所以我的问题是:

1. 如何从python代码中的注释自动生成swagger规范文件？
2. 我也使用JSON模式进行输入验证,如何将这些模式与swagger规范集成.

我的API是用龙卷风4.3在python 2.7.11中编写的.如果您有任何其他建议,请提出建议,而不是使用招摇.

更新:Apispec是一个有趣的开端,但它无法与JSON模式,截至目前被使用,所以不回答我的问题完全.

Answer 1

我们最近在工作中遇到了这个需求。我们制作了自己的生成器，它从 Google 风格的文档字符串生成 OpenAPI 3.0 api 规范。您只需要装饰处理程序和模型类。欲了解更多信息： https: //pypi.org/project/tornado-swirl/—— 尽管这项工作仍在进行中，但我们正在积极努力。

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()