forked from flier/tornado-rest-swagger
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
55 lines (42 loc) · 1.9 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
Installing
----------
1. ??? Install Swagger-UI libraries into /assets/lib/
2. If you're initializing your Tornado application like
class MyApplication(tornado.web.Application):
def __init__(self):
handlers = [
(r'/user/', UserHandler),
...
]
settings = dict(debug="True")
tornado.web.Application.__init__(self, handlers, **settings)
then add Swagger handlers like
swagger_handlers = tornado_rest_swagger.urls.handle_apidoc_urls(r'/swagger', **settings)
tornado.web.Application.__init__(self, handlers + swagger_handlers, **settings)
Documenting API methods
-----------------------
Write a docstrting in [epytext](http://epydoc.sourceforge.net/epytext.html) format like:
"""
Updates a user.
@type user: my.package.models.UserModel
@param user: The user JSON to be updated
@rtype: my.package.models.UserModel
"""
Full tag list is:
* @paramtype <name>: <http-parameter-type> (convention: defaults to 'path', could be 'query'. I can also think of 'body' and 'header'; might be arbitrary string).
* @type <name>: <dataType> (where dataType is a FQN like my.package.models.DeviceModel or a str/int/bool)
* @param <name>: <description>
bug: @type and @paramtype must go BEFORE a @param.
* @rtype <return type>
* @raisetype <error code>: <return type with the given code> (Apparently not supported by swagger-ui yet)
* @raise <error code>: <error reason>
bug: @raisetype must go BEFORE a @raise.
note: @return is a synonym of @raise for now.
* @note: <note>
* @summary: <summary>
bug: Each tag can have an argument and a body:
@raise <argument>: <body>.
If a tag has no body, it still must have a semicolon ':', otherwise it won't be seen by Swagger. Like:
@raise 200:
Missing: there's no way to describe an array of anything as a return type.
TODO: in-place model declaration for @type/@rtype