Browse files

Update documentation on schema.validate

  • Loading branch information...
1 parent 807c272 commit 42f6e140b2874191fe8b510fa6b88868c337194a @hfaran committed Mar 9, 2014
Showing with 40 additions and 52 deletions.
  1. +1 −1 demos/helloworld/helloworld/
  2. +11 −28 docs/requesthandler_guidelines.rst
  3. +25 −19 docs/using_tornado_json.rst
  4. +3 −4 tornado_json/
@@ -8,7 +8,7 @@ class HelloWorldHandler(APIHandler):
# Decorate any HTTP methods with the `schema.validate` decorator
# to validate input to it and output from it as per the
- # the schema for the method defined in `apid`
+ # the schema ``input_schema`` and ``output_schema`` arguments passed.
# Simply use `return` rather than `self.write` to write back
# your output.
@@ -5,41 +5,24 @@ Request Handler Guidelines
Schemas and Public API Documentation
-Create an ``apid`` dict in each RequestHandler as a class-level
-variable, i.e.,
-.. code:: python
- class ExampleHandler(APIHandler):
- apid = {}
-For each HTTP method you implement, add a corresponding entry in
-``apid``. The schemas must be valid JSON schemas;
-`readthedocs <>`__
-for an example. Here is an example for POST:
-.. code:: python
- apid["post"] = {
- "input_schema": ...,
- "output_schema": ...,
- "doc": ...,
- }
-``doc`` is the **public** accompanying documentation that will be
-available on the wiki.
Use the ``schema.validate`` decorator on methods which will automatically
-validate the request body and output against the schemas in
-``apid[method_name]``. Additionally, ``return`` the data from the
+validate the request body and output against the schemas provided. The schemas
+must be valid JSON schemas;
+`readthedocs <>`__
+for an example.
+Additionally, ``return`` the data from the
request handler, rather than writing it back (the decorator will take
care of that).
+The docstring of the method, as well as the schemas will be used to generate
+**public** API documentation.
.. code:: python
class ExampleHandler(APIHandler):
- @schema.validate
+ @schema.validate(input_schema=..., output_schema=...)
def post(self):
+ """I am the public API documentation of this route"""
return data
@@ -56,7 +39,7 @@ made. When using an assertion is not suitable,
.. code:: python
class ExampleHandler(APIHandler):
- @schema.validate
+ @schema.validate()
def post(self):
api_assert(condition, status_code, log_message=log_message)
@@ -61,49 +61,55 @@ Now comes the fun part where we develop the actual web app. We'll import
and the ``schema.validate`` decorator which will validate input and output
schema for us.
.. code:: python
from tornado_json.requesthandlers import APIHandler
from tornado_json import schema
class HelloWorldHandler(APIHandler):
- # apid
- # get(...)
+ @schema.validate(...)
+ def get(...):
+ ...
-Next, we'll define the ``apid`` class variable. ``apid`` is where we'll
-store the input and output schema for each HTTP method as well as the
-public API documentation for that route which will be automatically
+Next, we'll start writing our ``get`` method, but before writing the body,
+we'll define an output schema for it and pass it as an argument to the
+``schema.validate`` decorator which will automatically validate the output
+against the passed schema. In addition to the schema, the docstring
+for each HTTP method will be used by Tornado-JSON to generate public API
+documentation for that route which will be automatically
generated when you run the app (see the Documentation Generation section
for details). Input and output schemas are as per the `JSON
Schema <>`__ standard.
-.. code:: python
- apid = {
- "get": {
- "input_schema": None,
- "output_schema": {
- "type": "string",
- },
- "doc": "Shouts hello to the world!"
- },
- }
-Finally we'll write our ``get`` method which will write "Hello world!"
+.. code-block:: python
+ @schema.validate(output_schema={"type": "string"})
+ def get(self):
+ """Shouts hello to the world!"""
+ ...
+Finally we'll write our ``get`` method body which will write "Hello world!"
back. Notice that rather than using ``self.write`` as we usually would,
we simply return the data we want to write back, which will then be
validated against the output schema and be written back according to the
`JSend <>`__ specification. The
``schema.validate`` decorator handles all of this so be sure to decorate any
HTTP methods with it.
-.. code:: python
- @schema.validate
+.. code-block:: python
+ @schema.validate(output_schema={"type": "string"})
def get(self):
+ """Shouts hello to the world!"""
return "Hello world!"
Running our Hello World app
@@ -31,7 +31,7 @@ def _validate_example(rh, method, example_type):
return json.dumps(example, indent=4)
-def get_rh_methods(rh):
+def _get_rh_methods(rh):
"""Yield all HTTP methods in ``rh`` that are decorated
with schema.validate"""
for k, v in vars(rh).items():
@@ -46,8 +46,7 @@ def get_rh_methods(rh):
def api_doc_gen(routes):
Generates GitHub Markdown formatted API documentation using
- provided information from ``apid`` class-variable
- in each handler that provides one.
+ provided schemas in RequestHandler methods and their docstrings.
:type routes: [(url, RequestHandler), ...]
:param routes: List of routes (this is ideally all possible routes of the
@@ -109,7 +108,7 @@ def api_doc_gen(routes):
""".format(_validate_example(rh, method, "output")) if _validate_example(
rh, method, "output") else "",
- ) for method_name, method in get_rh_methods(rh)
+ ) for method_name, method in _get_rh_methods(rh)

0 comments on commit 42f6e14

Please sign in to comment.