-
Notifications
You must be signed in to change notification settings - Fork 60
/
api_doc_gen.py
83 lines (76 loc) · 2.24 KB
/
api_doc_gen.py
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
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
import logging
import json
def api_doc_gen(routes):
"""
Generates GitHub Markdown formatted API documentation using
provided information from `apid` class-variable
in each handler that provides one.
:type routes: [(url, RequestHandler), ...]
:param routes: List of routes (this is ideally all possible routes of the
app)
"""
documentation = []
# Iterate over routes sorted by url
for url, rh in sorted(routes, key=lambda a: a[0]):
try:
# Content-type is hard-coded but ideally should be retrieved;
# the hard part is, we don't know what it is without initializing
# an instance, so just leave as-is for now
route_doc = """
# `{0}`
Content-Type: application/json
{1}
""".format(
url,
"\n\n".join(
[
"""## {0}
### Input Schema
```json
{1}
```
{4}
### Output Schema
```json
{2}
```
{5}
{3}
""".format(
method.upper(),
json.dumps(rh.apid[method]
["input_schema"], indent=4),
json.dumps(rh.apid[method]
["output_schema"], indent=4),
rh.apid[method]["doc"],
"""
### Input Example
```json
{}
```
""".format(json.dumps(rh.apid[method]["input_example"], indent=4))
if rh.apid[method].get("input_example") else "",
"""
### Output Example
```json
{}
```
""".format(json.dumps(rh.apid[method]["output_example"], indent=4))
if rh.apid[method].get("output_example") else "",
) for method in list(rh.apid.keys())
]
)
)
documentation.append(route_doc)
# If a RequestHandler does not yet have an apid variable
# just ignore it and continue
except AttributeError as e:
logging.info(str(e))
continue
# Documentation is written to the root folder
with open("API_Documentation.md", "w+") as f:
f.write(
"**This documentation is automatically generated.**\n\n" +
"**Output schemas only represent `data` and not the full output; see output examples and the JSend specification.**\n" +
"\n\n\n".join(documentation)
)