从Tornado Web服务器代码生成交互式API文档

Question

我有一个Tornado Web服务器，暴露了一些API端点。我希望能够在代码中记录我的处理程序（端点），包括描述、参数、示例、响应结构等，然后生成一个交互式文档，使用户可以“玩耍”我的API，在沙盒环境中轻松地进行请求并体验响应。

我知道Swagger，特别是他们的SwaggerUI解决方案是最好的工具之一，但我对它的工作方式感到困惑。我理解我需要向SwaggerUI引擎提供一些定义我的API的.yaml，但我如何从我的代码中生成它呢？我发现许多GitHub库都不够好或只支持Flask...

谢谢

- mllm

Answer 1

据我所知，SwaggerUI依赖于swagger规范。
因此，归根结底，它需要以一种简洁优美的方式生成Swagger规范。
你有没有看过apispec？
我发现这是一个活跃的项目，还带有tornado插件。

- yottabytt

Answer 2

以下是我们在项目中的做法。我们制作了自己的模块，并且仍在积极开发中。更多信息请参见：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()

- Rodolfo Narciso Duldulao Jr.