wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add in response format for APIs. Standardise on 'key' rather than 'name'.

Browse source
This commit is contained in:
Kegan Dougal 2015-06-01 15:54:16 +01:00
parent f6c98f41e9
commit 704cd14030
2 changed files with 34 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

18
templating/matrix_templates/templates/http-api.tmpl
View file

@ -15,11 +15,23 @@ Request format:
**{{loc}} parameters**
--------------------------------------------------------------------------------
{% for param in endpoint.req_param_by_loc[loc] -%}
{{param.name}}{{param.type|indent(19-param.name|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(37)}}
{% endfor %}
{% endfor %}
{{param.key}}{{param.type|indent(19-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(37)}}
{% endfor -%}
{% endfor -%}
================== ================= ===========================================
{% if endpoint.res_params|length > 0 -%}
Response format:
================== ================= ===========================================
Parameter Value Description
================== ================= ===========================================
{% for param in endpoint.res_params -%}
{{param.key}}{{param.type|indent(19-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(37)}}
{% endfor -%}
================== ================= ===========================================
{% endif %}
Example request::
{{endpoint.example.req | indent_block(2)}}

22
templating/matrix_templates/units.py
View file

@ -112,6 +112,7 @@ class MatrixUnits(Units):
"requires_auth": "security" in single_api,
"rate_limited": 429 in single_api.get("responses", {}),
"req_params": [],
"res_params": [],
"example": {
"req": "",
"res": ""
@ -134,7 +135,7 @@ class MatrixUnits(Units):
val_type = schemaFmt
if val_type:
endpoint["req_params"].append({
"name": param["name"],
"key": param["name"],
"loc": param["in"],
"type": val_type,
"desc": desc
@ -160,13 +161,12 @@ class MatrixUnits(Units):
json_body = Units.prop(param, "schema/properties")
for key in json_body:
endpoint["req_params"].append({
"name": key,
"key": key,
"loc": "JSON body",
"type": json_body[key]["type"],
"desc": json_body[key]["description"]
})
# endfor[param]
# group params by location to ease templating
endpoint["req_param_by_loc"] = {
# path: [...], query: [...], body: [...]
@ -213,6 +213,22 @@ class MatrixUnits(Units):
"The following parameters are missing examples :( \n %s" %
[ p["name"] for p in params_missing_examples ]
)
# add response params if this API has any.
res_type = Units.prop(res, "schema/type")
if res_type and res_type not in ["object", "array"]:
# response is a raw string or something like that
endpoint["res_params"].append({
"key": res["schema"].get("name", ""),
"type": res_type,
"desc": res.get("description", "")
})
elif res_type and Units.prop(res, "schema/properties"): # object
res_tables = get_json_schema_object_fields(res["schema"])
# TODO: Is this good enough or should we be doing multiple
# tables for HTTP responses?!
endpoint["res_params"] = res_tables[0]["rows"]
endpoints.append(endpoint)
return {