Tornado-Swagger 使用教程

Tornado-Swagger 使用教程

tornado-swagger Swagger API Documentation builder for tornado server. 项目地址: https://gitcode.com/gh_mirrors/to/tornado-swagger

项目概述

Tornado-Swagger 是一个专为Tornado服务器设计的插件，它使得API文档化变得更加简便，并集成了Swagger UI界面（默认访问路径为 /api/doc）。此工具支持Python版本从3.7到3.11，包括夜间版本，遵循MIT许可协议。

目录结构及介绍

以下是一个典型的 tornado-swagger 项目可能的目录结构示例及其简介：

• root
  • src 或直接在根目录下：存放应用程序的源代码。
    • 包含处理请求的 handlers（如 handlers.py），其中可以定义使用Swagger注解的路由。
    • 可能还有模型定义（models.py）和初始化设置等。
  • tornado_swagger：这个是安装了tornado-swagger之后，库文件存放的位置，通常不直接包含在你的项目中，但了解其存在有助于理解如何集成Swagger功能。
  • static：如果手动管理静态资源，可能用于存放Swagger UI相关的CSS和JS文件，尽管现在推荐使用CDN。
  • templates：用来存放任何自定义的Swagger UI模板或者特定的HTML页面。
  • tests：单元测试和集成测试的文件夹。
  • requirements.txt 或 requirements-dev.txt：列出项目运行或开发所需的依赖项。
  • setup.cfg 和 setup.py：项目构建和元数据配置文件。
  • README.rst: 文档说明文件，介绍了如何安装和快速上手项目。
  • .gitignore: 确定哪些文件不应被Git版本控制系统跟踪。
  • LICENSE: 许可证文件，声明软件使用的许可证类型，这里是MIT许可证。

启动文件介绍

在Tornado应用中，启动文件通常是入口点，比如 main.py 或 app.py。它负责初始化Tornado Web服务器并设置所有必要的中间件，包括注册Tornado-Swagger插件。一个基础的启动文件示例如下：

import tornado.ioloop
import tornado.web
from tornado_swagger.setup import setup_swagger
from handlers import PostsDetailsHandler  # 示例处理器

def make_app():
    handlers = [
        (r"/posts/([0-9]+)", PostsDetailsHandler),  # 假设这是个API端点
    ]
    settings = dict(
        template_path="templates",
        static_path="static",
        swagger specs=(("API", "/", "api"),),
    )
    # 集成Swagger
    app = tornado.web.Application(handlers, **settings)
    setup_swagger(app, api_base_url="/api")  # 初始化Swagger
    return app

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

配置文件介绍

在tornado-swagger中，配置主要通过代码来实现，而不是传统的外部配置文件（如.ini或.yaml）。然而，你可以利用Python的配置方式来设定插件的行为。配置项一般嵌入在你的应用初始化过程中，如下所示：

settings = {
    "swagger_ui_index": "custom_index.html",  # 若有自定义Swagger UI首页，则指定路径
    "swagger_docs": {  # 定义Swagger文档路径和URL映射
        "api_doc": ("/api/doc", "api/swagger.yaml"),
    },
    "displayOperationId": True,  # 是否显示operationId，默认为False
}

# 然后在创建Application时传入这些设置
app = tornado.web.Application(handlers, **settings)
setup_swagger(app, **settings)  # 传递配置

以上就是tornado-swagger的基本项目结构、启动文件以及配置文件的简介。记得在正式开发前阅读项目在GitHub上的具体文档和示例，以获取更详细的信息和最佳实践指导。

tornado-swagger Swagger API Documentation builder for tornado server. 项目地址: https://gitcode.com/gh_mirrors/to/tornado-swagger