Tornado OpenAPI 3

Tornado OpenAPI 3 request and response validation library.

Provides integration between the Tornado web framework and Openapi-core library for validating request and response objects against an OpenAPI 3 specification.

Full documentation is available at https://tornado-openapi3.readthedocs.io

Usage

Adding validation to request handlers

import tornado.ioloop
import tornado.web
from tornado_openapi3.handler import OpenAPIRequestHandler


class MyRequestHandler(OpenAPIRequestHandler):
    spec_dict = {
        "openapi": "3.0.0",
        "info": {
            "title": "Simple Example",
            "version": "1.0.0",
        },
        "paths": {
            "/": {
                "get": {
                    "responses": {
                        "200": {
                            "description": "Index",
                            "content": {
                                "text/html": {
                                    "schema": {"type": "string"},
                                }
                            },
                        }
                    }
                }
            }
        },
    }


class RootHandler(MyRequestHandler):
    async def get(self):
        self.finish("Hello, World!")


if __name__ == "__main__":
    app = tornado.web.Application([(r"/", RootHandler)])
    app.listen(8888)
    tornado.ioloop.IOLoop.current().start()

Validating responses in tests

import unittest

import tornado.web
from tornado_openapi3.testing import AsyncOpenAPITestCase


class RootHandler(tornado.web.RequestHandler):
    async def get(self):
        self.finish("Hello, World!")


class BaseTestCase(AsyncOpenAPITestCase):
    spec_dict = {
        "openapi": "3.0.0",
        "info": {
            "title": "Simple Example",
            "version": "1.0.0",
        },
        "paths": {
            "/": {
                "get": {
                    "responses": {
                        "200": {
                            "description": "Index",
                            "content": {
                                "text/html": {
                                    "schema": {"type": "string"},
                                }
                            },
                        }
                    }
                }
            }
        },
    }

    def get_app(self):
        return tornado.web.Application([(r"/", RootHandler)])

    def test_root_endpoint(self):
        response = self.fetch("/")
        self.assertEqual(200, response.code)
        self.assertEqual(b"Hello, World!", response.body)


if __name__ == "__main__":
    unittest.main()

Contributing

Getting Started

This project uses Poetry to manage its dependencies. To set up a local development environment, just run:

poetry install

Formatting Code

The Black tool is used by this project to format Python code. It is included as a development dependency, and should be run on all committed code. To format code prior to committing it and submitting a PR, run:

poetry run black .

Running Tests

pytest is the preferred test runner for this project. It is included as a development dependency, and is configured to track code coverage, Flake8 style compliance, and Black code formatting. Tests can be run in your development environment by running:

poetry run pytest

Additionally, tests can be run using tox, which will run the tests using multiple versions of both Python and Tornado to ensure broad compatibility.

Configuring Hypothesis

Many of the tests make use of Hypothesis to specify their expectations and generate a large volume of randomized test input. Because of this, the tests may take a long time to run on slower computers. Two profiles are defined for Hypothesis to use which can be selected by setting the HYPOTHESIS_PROFILE environment variable to one of the following values:

ci

Runs tests using the default Hypothesis settings (100 examples per test) and no completion deadline.

dev

The fastest profile, meant for local development only. Uses only 10 examples per test with no completion deadline.