archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #330 from matrix-org/rav/improve_examples

Browse Source 
Improve API examples in the spec
pull/977/head
Richard van der Hoff 8 years ago
parent 2d28e5abce 167b84cc7f
commit 0cdc2da5bf
2 changed files with 75 additions and 53 deletions
Show Stats Download Patch File Download Diff File

11
templating/matrix_templates/templates/http-api.tmpl
Unescape Escape View File

@ -44,22 +44,25 @@ Example request:
{{endpoint.example.req | indent_block(2)}}
{% if endpoint.example.responses|length > 0 -%}
Response{{"s" if endpoint.example.responses|length > 1 else "" }}:
{% if endpoint.responses|length > 0 -%}
Response{{"s" if endpoint.responses|length > 1 else "" }}:
{% endif -%}
{% for res in endpoint.example.responses -%}
{% for res in endpoint.responses -%}
**Status code {{res["code"]}}:**
{{res["description"]}}
{% if res["example"] -%}
Example
.. code:: json
{{res["example"] | indent_block(2)}}
{% endfor %}
{% endif -%}
{% endfor %}

117
templating/matrix_templates/units.py
Unescape Escape View File

@ -99,10 +99,11 @@ def get_json_schema_object_fields(obj, enforce_title=False,
obj["title"] = 'NO_TITLE'
additionalProps = obj.get("additionalProperties")
if additionalProps:
props = obj.get("properties")
if additionalProps and not props:
# not "really" an object, just a KV store
additionalProps = inherit_parents(additionalProps)
# not "really" an object, just a KV store
logger.debug("%s is a pseudo-object", obj.get("title"))
key_type = additionalProps.get("x-pattern", "string")
@ -127,7 +128,6 @@ def get_json_schema_object_fields(obj, enforce_title=False,
logger.debug("%s done: returning %s", obj.get("title"), tables)
return tables
props = obj.get("properties")
if not props:
props = obj.get("patternProperties")
if props:
@ -273,9 +273,34 @@ def get_tables_for_schema(schema, mark_required=True):
return filtered
def get_example_for_schema(schema):
"""Returns a python object representing a suitable example for this object"""
if 'example' in schema:
example = schema['example']
return example
if 'properties' in schema:
res = {}
for prop_name, prop in schema['properties'].iteritems():
logger.debug("Parsing property %r" % prop_name)
prop_example = get_example_for_schema(prop)
res[prop_name] = prop_example
return res
if 'items' in schema:
return [get_example_for_schema(schema['items'])]
return schema.get('type', '??')
def get_example_for_param(param):
if 'x-example' in param:
return param['x-example']
schema = param.get('schema')
if not schema:
return None
if 'example' in schema:
return schema['example']
return json.dumps(get_example_for_schema(param['schema']),
indent=2)
class MatrixUnits(Units):
def _load_swagger_meta(self, api, group_name):
endpoints = []
for path in api["paths"]:
@ -293,10 +318,9 @@ class MatrixUnits(Units):
"req_param_by_loc": {},
"req_body_tables": [],
"res_tables": [],
"responses": [],
"example": {
"req": "",
"responses": [],
"good_response": ""
}
}
self.log(" ------- Endpoint: %s %s ------- " % (method, path))
@ -330,60 +354,55 @@ class MatrixUnits(Units):
# endfor[param]
good_response = None
for code, res in single_api.get("responses", {}).items():
for code in sorted(single_api.get("responses", {}).keys()):
res = single_api["responses"][code]
if not good_response and code == 200:
good_response = res
description = res.get("description", "")
example = res.get("examples", {}).get("application/json", "")
if description and example:
endpoint["example"]["responses"].append({
"code": code,
"description": description,
"example": example,
})
endpoint["responses"].append({
"code": code,
"description": description,
"example": example,
})
path_template = api.get("basePath", "").rstrip("/") + path
qps = []
body = ""
for param in single_api.get("parameters", []):
try:
example = get_example_for_param(param)
if not example:
self.log(
"The parameter %s is missing an example." %
param["name"])
continue
# form example request if it has one. It "has one" if all params
# have either "x-example" or a "schema" with an "example".
params_missing_examples = [
p for p in single_api.get("parameters", []) if (
"x-example" not in p and
not Units.prop(p, "schema/example")
)
]
if len(params_missing_examples) == 0:
path_template = api.get("basePath", "").rstrip("/") + path
qps = []
body = ""
for param in single_api.get("parameters", []):
if param["in"] == "path":
path_template = path_template.replace(
"{%s}" % param["name"], urllib.quote(
param["x-example"]
)
"{%s}" % param["name"], urllib.quote(example)
)
elif param["in"] == "body":
body = param["schema"]["example"]
body = example
elif param["in"] == "query":
example = param["x-example"]
if type(example) == list:
for value in example:
qps.append((param["name"], value))
else:
qps.append((param["name"], example))
query_string = "" if len(qps) == 0 else "?"+urllib.urlencode(qps)
if body:
endpoint["example"]["req"] = "%s %s%s HTTP/1.1\nContent-Type: application/json\n\n%s" % (
method.upper(), path_template, query_string, body
)
else:
endpoint["example"]["req"] = "%s %s%s HTTP/1.1\n\n" % (
method.upper(), path_template, query_string
)
else:
qps.append((param["name"], example))
except Exception, e:
raise Exception("Error handling parameter %s" % param["name"],
e)
query_string = "" if len(qps) == 0 else "?"+urllib.urlencode(qps)
if body:
endpoint["example"]["req"] = "%s %s%s HTTP/1.1\nContent-Type: application/json\n\n%s" % (
method.upper(), path_template, query_string, body
)
else:
self.log(
"The following parameters are missing examples :( \n %s" %
[ p["name"] for p in params_missing_examples ]
endpoint["example"]["req"] = "%s %s%s HTTP/1.1\n\n" % (
method.upper(), path_template, query_string
)
# add response params if this API has any.
@ -465,9 +484,9 @@ class MatrixUnits(Units):
try:
req_body_tables = get_tables_for_schema(param["schema"])
except Exception, e:
logger.warning("Error decoding body of API endpoint %s %s: %s",
endpoint_data["method"], endpoint_data["path"],
e.args[0])
logger.warning("Error decoding body of API endpoint %s %s" %
(endpoint_data["method"], endpoint_data["path"]),
exc_info=1)
return
# put the top-level parameters into 'req_param_by_loc', and the others

Write Preview
Loading…
Cancel
Save