3 ## What is tornado-swagger?
4 tornado is a wrapper for tornado which enables swagger-ui support.
6 In essense, you just need to wrap the Api instance and add a few python decorators to
7 get full swagger support.http://swagger.io/
14 from tornado.web import RequestHandler, HTTPError
15 from tornado_swagger import swagger
19 # You may decorate your operation with @swagger.operation and use docs to inform information
20 class ItemNoParamHandler(GenericApiHandler):
21 @swagger.operation(nickname='create')
24 @param body: create test results for a item.
26 @return 200: item is created.
27 @raise 400: invalid input
30 # Operations not decorated with @swagger.operation do not get added to the swagger docs
32 class ItemNoParamHandler(GenericApiHandler):
35 I'm not visible in the swagger docs
40 # Then you use swagger.Application instead of tornado.web.Application
41 # and do other operations as usual
44 return swagger.Application([
45 (r"/items", ItemNoParamHandler),
46 (r"/items/([^/]+)", ItemHandler),
47 (r"/items/([^/]+)/cases/([^/]+)", ItemOptionParamHandler),
50 # You define models like this:
55 This is an example of a model class that has parameters in its constructor
56 and the fields in the swagger spec are derived from the parameters to __init__.
58 In this case we would have property1, property2 as required parameters
59 and property3 as optional parameter.
60 @property property3: Item decription
61 @ptype property3: L{PropertySubclass}
63 def __init__(self, property1, property2=None):
64 self.property1 = property1
65 self.property2 = property2
70 "description": "A description...",
87 # If you declare an __init__ method with meaningful arguments
88 # then those args could be used to deduce the swagger model fields.
91 # if you declare an @property in docs, this property property2 will also be used
92 # to deduce the swagger model fields
95 @property property3: Item description
97 def __init__(self, property1, property2):
98 self.property1 = property1
99 self.property2 = property2
104 "description": "A description...",
123 # if you declare an argument with @ptype, the type of this argument will be specified
124 # rather than the default 'string'
127 @ptype property3: L{PropertySubclass}
129 def __init__(self, property1, property2, property3=None):
130 self.property1 = property1
131 self.property2 = property2
132 self.property3 = property3
137 "description": "A description...",
150 "type": "PropertySubclass"
157 # if you want to declare an list property, you can do it like this:
160 @ptype property3: L{PropertySubclass}
161 @ptype property4: C{list} of L{PropertySubclass}
163 def __init__(self, property1, property2, property3, property4=None):
164 self.property1 = property1
165 self.property2 = property2
166 self.property3 = property3
167 self.property4 = property4
172 "description": "A description...",
185 "type": "PropertySubclass"
191 "type": "PropertySubclass"},
200 class ItemQueryHandler(GenericApiHandler):
201 @swagger.operation(nickname='query')
205 @type property1: L{string}
207 @required property1: False
210 @type property2: L{string}
212 @required property2: True
215 @notes: GET /item?property1=1&property2=1
226 "dataType": "string",
227 "paramType": "query",
232 "dataType": "string",
233 "paramType": "query",
238 "responseClass": "Item",
240 "responseMessages": [],
253 # Running and testing
255 Now run your tornado app
264 curl http://ip:port/swagger/spec
269 http://ip:port/swagger/spec.html
272 # Passing more metadata to swagger
273 customized arguments used in creating the 'swagger.docs' object will be supported later