tornado集成swagger

关于

swagger相信大家都不陌生了，但是除了一些主流的框架，小众一点的群体想和现有项目交互集成还是比较困难，网上关于Tornado框架集成Swagger的教程很少，最近整理了一下今天给大家介绍写法和用例等。

安装插件

pip install tornado_swagger

启动类引入相关配置

from tornado_swagger.setup import setup_swagger
        在原有启动应用程序的方法上加入以下配置
        setup_swagger(routes ,
                      swagger_url='/swagger',
                      api_base_url="/spec",
                      description="用于模板展示的API接口事例和说明",
                      title="模板API列表",schemes=["http"])
        tornado.web.Application.__init__(self, handlers, **settings)

基本参数解释：
routes ：路由注册。
swagger_url：访问swagger的路径。
title: 可选参数，指定 SwaggerUI 的标题。
description: 可选参数，指定 Swagger UI 的描述。
schemes: 可选参数，指定支持的协议。
还有其他的一些可选配置，在这里就不都说明啦~

使用并生成相关内容

如果要描述的接口为post类型，则在handler处理类下新增一个post方法，在下面填写相关参数注释。如下文：

    def post(self):
        """
        ---
        tags:
        - 店铺数据处理
        summary: 获取列表数据
        description: 查询所在店铺的信息并展示
        produces:
        - application/json
        parameters:
        -   name: body
            in: body
            schema:
              type: object
              properties:
               page_num:
                 type: number
                 required: true
                 default: 1
               page_size:
                 type: number
                 default: 10
                 required: true
               product_id:
                 type:  number
               prdouct_name:
                 type:  string
        responses:
            200:
              description: success
            500:
              description: faild
        """

写完以后将对应的route注册到swagger:

routes = [
        tornado.web.url(r'/store/get_list', PostsHandler),
        tornado.web.url(r'/store/(\w+)', PostsDetailsHandler),
    ]

然后打开浏览器访问程序所在端口加上/swagger路径


返回值是实体model的时候在代码里引入

from tornado_swagger.model import register_swagger_model

@register_swagger_model
class StoreModel:
    """
    ---
    type: object
    description: Post model representation
    properties:
        store_id:
            type: string
        title:
            type: string
        text:
            type: string
        is_visible:
            type: boolean
            default: true
    """
#然后修改对应的注释，在返回的状态码中添加
           responses:
            200:
              description: success
              schema:
                $ref: '#/definitions/StoreModel'

这样返回值也会显示在swagger的ui页面上了，也可以配置参数描述等。

同理，get方法和put等请求方式也是一样的，不过根据传参的类型和返回值的结构再做相应的修改就好了。

现在是不是觉得非常简单呢，只是有些参数可能大家还比较懵，在这里一起解释一下：

• summary：接口的简要描述，通常只包含一句话。

• description：接口的详细描述，通常包含接口的实现逻辑、输入输出参数等信息。

• tags：接口所属的标签，用于对接口进行分类和分组。

• name：输入参数的名称。

• in：参数的位置，可以是query、header、path、formData或body，其中最常见的是query和body。

• query：查询字符串中的参数，如/users?name=John&age=20中的name和age。

• header：HTTP请求头中的参数，如Authorization、Content-Type等。

• path：路径参数，如/users/{id}中的id。

• formData：表单数据，通常用于POST请求中的表单提交。

• body：请求体中的数据，通常用于发送JSON、XML等非表单数据。

• type：参数的数据类型，可以是integer、number、string、boolean、array或object。

• description：参数的描述信息。

• required：参数是否为必选项，可选值为true或false。

• default：参数的默认值。

• minimum：参数的最小值。

• maximum：参数的最大值。

• responses：接口可能返回的HTTP响应。

• 200、400：HTTP响应的状态码，成功、失败等几种常见状态。

• description：HTTP响应的描述信息。

• schema：HTTP响应所包含的数据结构。

• $ref：引用某个定义，例如#definitions/User表示引用名为User的数据结构定义。

  如果觉得内容对你有帮助，记得一键三连喔亲~~~