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

【问题标题】：Generate interactive API docs from Tornado web server code从 Tornado Web 服务器代码生成交互式 API 文档
【发布时间】：2017-03-20 09:51:22
【问题描述】：

我有一个 Tornado Web 服务器，它在其 API 中公开了一些端点。我希望能够记录我的处理程序（端点）in-code，包括描述、参数、示例、响应结构等，然后生成一个 interactive 文档使人们能够“玩”我的 API，轻松地发出请求并在沙盒环境中体验响应。

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

谢谢

【问题讨论】：

标签： documentation swagger tornado swagger-ui api-doc

【解决方案1】：

据我了解，SwaggerUI 依赖于 swagger 规范。
因此，归结为以简洁优雅的方式生成 Swagger 规范。
你有机会看看apispec吗？
我发现这是一个带有龙卷风插件的活跃项目。

【讨论】：

【解决方案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()

【讨论】：