tornado-swagger 1.7.0

Links

• Documentation: https://github.com/mrk-andreev/tornado-swagger/wiki

• Source code: https://github.com/mrk-andreev/tornado-swagger

• Issues: https://github.com/mrk-andreev/tornado-swagger/issues

• PyPI: https://pypi.org/project/tornado-swagger/

• Swagger 2.0 specification: https://swagger.io/specification/v2/

• OpenAPI specification: https://swagger.io/specification/

Installation

pip install -U tornado-swagger

Requirements

• Python 3.6 through 3.14

• Tornado 5.0 or newer

• PyYAML 5.4 or newer

Standards compatibility

tornado-swagger generates documents compatible with Swagger 2.0, OpenAPI 3.0.3, and OpenAPI 3.1.0. Compatibility tests validate generated documents against the corresponding standards. Valid operation, schema, parameter, response, request body, and security YAML blocks are passed through into the generated document for the selected standard.

Quick start

Add YAML documentation to Tornado handler method docstrings after a --- separator, then call setup_swagger before constructing the application.

import tornado.ioloop
import tornado.web

from tornado_swagger.setup import setup_swagger


class ExampleHandler(tornado.web.RequestHandler):
    def get(self):
        """
        ---
        tags:
        - Example
        summary: Get an example response
        produces:
        - application/json
        responses:
            200:
              description: Successful response
        """
        self.write({"ok": True})


routes = [
    tornado.web.url(r"/api/example", ExampleHandler),
]

setup_swagger(
    routes,
    swagger_url="/api/doc",
    api_base_url="/",
    title="Example API",
    api_version="1.0.0",
)

app = tornado.web.Application(routes)
app.listen(8080)
tornado.ioloop.IOLoop.current().start()

Open http://localhost:8080/api/doc to view Swagger UI. The generated schema is served at http://localhost:8080/api/doc/swagger.json.

Models and Parameters

Reusable definitions can be registered with decorators. For Swagger 2.0, refer to models with #/definitions/... and parameters with #/parameters/....

import tornado.web
from tornado_swagger.model import register_swagger_model
from tornado_swagger.parameter import register_swagger_parameter


class PostsDetailsHandler(tornado.web.RequestHandler):
    def get(self, posts_id):
        """
        ---
        tags:
        - Posts
        summary: Get posts details
        description: posts full version
        produces:
        - application/json
        parameters:
        -   $ref: '#/parameters/PostId'
        responses:
            200:
              description: list of posts
              schema:
                $ref: '#/definitions/PostModel'
        """


@register_swagger_parameter
class PostId:
    """
    ---
    name: posts_id
    in: path
    description: ID of post
    required: true
    type: string
    """


@register_swagger_model
class PostModel:
    """
    ---
    type: object
    description: Post model representation
    properties:
        id:
            type: integer
            format: int64
        title:
            type: string
        text:
            type: string
        is_visible:
            type: boolean
            default: true
    """

OpenAPI 3

OpenAPI 3 support is available by passing API_OPENAPI_3 or API_OPENAPI_3_1 to setup_swagger or export_swagger. API_OPENAPI_3 emits OpenAPI 3.0.3, while API_OPENAPI_3_1 emits OpenAPI 3.1.0. OpenAPI 3 references use #/components/schemas/... and #/components/parameters/.... OpenAPI 3 security schemes can be passed with security_schemes.

from tornado_swagger.const import API_OPENAPI_3
from tornado_swagger.setup import setup_swagger


setup_swagger(
    routes,
    api_definition_version=API_OPENAPI_3,
)

JWT bearer authentication requires OpenAPI 3 because Swagger 2.0 does not support type: http security schemes.

from tornado_swagger.const import API_OPENAPI_3
from tornado_swagger.setup import setup_swagger


setup_swagger(
    routes,
    api_definition_version=API_OPENAPI_3,
    security_schemes={
        "BearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "bearerFormat": "JWT",
        },
    },
    security=[{"BearerAuth": []}],
)

Configuration

setup_swagger(routes, **kwargs) inserts Swagger UI and schema routes at the front of the supplied route list.

Supported options:

• swagger_url: UI URL prefix. Defaults to /api/doc.

• api_base_url: API base path in the generated schema. Defaults to /. Swagger 2 emits this as basePath; OpenAPI 3 emits it as servers[0].url.

• strip_prefix: Optional route path prefix to remove from generated paths. Use this when Tornado routes include a deployment prefix that is already represented by api_base_url.

• description: API description text.

• api_version: API version string.

• title: API title.

• contact: Contact name included in the schema.

• schemes: Swagger 2 scheme list, for example ["https"].

• security_definitions: Swagger 2 security definitions to include in the schema. For backwards compatibility, OpenAPI 3 also accepts this option and emits it as components.securitySchemes.

• security_schemes: OpenAPI 3 security schemes to include under components.securitySchemes.

• security: Global security requirements.

• display_models: Show or hide the Swagger UI models panel. Defaults to True.

• api_definition_version: API_SWAGGER_2 by default, or API_OPENAPI_3 / API_OPENAPI_3_1.

• allow_cors: Add CORS headers to Swagger UI and swagger.json responses (both the GET and preflight OPTIONS responses). Defaults to False.

• cors_origin: Value for the Access-Control-Allow-Origin header when allow_cors is enabled. Defaults to "*". Set a specific origin (e.g. "https://example.com") to restrict cross-origin access; a Vary: Origin header is then added automatically.

• swagger_ui_version: Swagger UI release loaded from cdnjs. Defaults to "4.13.2". When you change it, also pass the matching subresource integrity (SRI) hashes via the options below, otherwise the browser will block the assets.

• swagger_ui_css_sri / swagger_ui_bundle_sri / swagger_ui_preset_sri: SRI hashes for swagger-ui.min.css, swagger-ui-bundle.min.js and swagger-ui-standalone-preset.min.js respectively. Defaults match swagger_ui_version’s default. Find the hashes for a given release on its cdnjs page. Pass empty strings to disable integrity checking.

To generate the schema without installing UI routes, use export_swagger:

from tornado_swagger.setup import export_swagger


schema = export_swagger(routes, title="Example API", api_version="1.0.0")

Examples

Runnable examples are available in the examples directory:

• examples/simple_server.py: minimal Swagger UI setup.

• examples/model_and_param_declaration.py: reusable Swagger 2 models and parameters.

• examples/model_and_param_declaration_openapi3.py: OpenAPI 3 output.

• examples/auth_server.py and examples/under_security/app.py: security-related examples.

• examples/decorated_handlers.py: documented handlers with decorators.

• examples/args_recognize.py: route argument name recognition.

Development

Install runtime and development dependencies, then run tests and linters with the Makefile targets:

pip install -r requirements-dev.txt
make test
make lint

Additional targets:

• make format: run Ruff fixes and Black formatting.

• make test-matrix: run the tox matrix.

• make test-in-docker: run the Docker-based Python version matrix.

The tox matrix covers Tornado 5.0, 6.0, and 6.5.6 on older supported Python versions, and Tornado 6.5.6 on Python 3.11, 3.12, 3.13, and 3.14.

What’s new?

License