Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update documentation on schema.validate

  • Loading branch information...
commit 42f6e140b2874191fe8b510fa6b88868c337194a 1 parent 807c272
@hfaran authored
View
2  demos/helloworld/helloworld/api.py
@@ -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.
@schema.validate(
View
39 docs/requesthandler_guidelines.rst
@@ -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 <https://python-jsonschema.readthedocs.org/en/latest/>`__
-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 <https://python-jsonschema.readthedocs.org/en/latest/>`__
+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)
View
44 docs/using_tornado_json.rst
@@ -61,6 +61,7 @@ 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
@@ -68,29 +69,31 @@ schema for us.
class HelloWorldHandler(APIHandler):
"""Hello!"""
- # 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 <http://json-schema.org/>`__ 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
@@ -98,12 +101,15 @@ validated against the output schema and be written back according to 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
View
7 tornado_json/api_doc_gen.py
@@ -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)
]
)
)
Please sign in to comment.
Something went wrong with that request. Please try again.