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

Use table subsections for param locations instead of an extra column.

Browse source
This commit is contained in:
Kegan Dougal 2015-06-01 15:26:48 +01:00
parent ba6ce16509
commit f6c98f41e9
3 changed files with 24 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

2
api/client-server/v1/profile.yaml
View file

@ -107,7 +107,7 @@ paths:
type: object type: object
example: |- example: |-
{ {
"avatar_url": "mxc:/matrix.org/wefh34uihSDRGhw34" "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
} }
properties: properties:
avatar_url: avatar_url:

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

@ -8,14 +8,17 @@
Request format: Request format:
================== ================= =========== =============================== ================== ================= ===========================================
Parameter Param Location Param Type Description Parameter Value Description
================== ================= =========== =============================== ================== ================= ===========================================
{% for param in endpoint.req_params -%} {% for loc in endpoint.req_param_by_loc -%}
{{param.name}}{{param.loc|indent(19-param.name|length)}}{{param.type|indent(37-19- **{{loc}} parameters**
param.loc|length)}}{{param.desc|indent(12-param.type|length)|wrap(31)|indent_block(49)}} --------------------------------------------------------------------------------
{% 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 %}
================== ================= =========== =============================== {% endfor %}
================== ================= ===========================================
Example request:: Example request::

41
templating/matrix_templates/units.py
View file

@ -112,9 +112,6 @@ class MatrixUnits(Units):
"requires_auth": "security" in single_api, "requires_auth": "security" in single_api,
"rate_limited": 429 in single_api.get("responses", {}), "rate_limited": 429 in single_api.get("responses", {}),
"req_params": [], "req_params": [],
"responses": [
# { code: 200, [ {row_info} ]}
],
"example": { "example": {
"req": "", "req": "",
"res": "" "res": ""
@ -164,35 +161,24 @@ class MatrixUnits(Units):
for key in json_body: for key in json_body:
endpoint["req_params"].append({ endpoint["req_params"].append({
"name": key, "name": key,
"loc": "JSON", "loc": "JSON body",
"type": json_body[key]["type"], "type": json_body[key]["type"],
"desc": json_body[key]["description"] "desc": json_body[key]["description"]
}) })
# endfor[param]
# add main response format first. # group params by location to ease templating
res200 = single_api["responses"][200] endpoint["req_param_by_loc"] = {
res200params = [] # path: [...], query: [...], body: [...]
if res200["schema"].get("type") != "object":
res200params = [{
"title": "Response",
"rows": [{
"key": res200["schema"]["name"],
"type": res200["schema"]["type"],
"desc": res200["schema"].get("description", "")
}]
}]
elif res200["schema"].get("properties"):
res200params = get_json_schema_object_fields(
res200["schema"]
)
ok_res = {
"code": 200,
"http": "200 OK",
"desc": res200["description"],
"params": res200params
} }
for p in endpoint["req_params"]:
if p["loc"] not in endpoint["req_param_by_loc"]:
endpoint["req_param_by_loc"][p["loc"]] = []
endpoint["req_param_by_loc"][p["loc"]].append(p)
# add example response if it has one # add example response if it has one
endpoint["example"]["res"] = res200.get("examples", {}).get( res = single_api["responses"][200] # get the 200 OK response
endpoint["example"]["res"] = res.get("examples", {}).get(
"application/json", "" "application/json", ""
) )
# form example request if it has one. It "has one" if all params # form example request if it has one. It "has one" if all params
@ -227,9 +213,8 @@ class MatrixUnits(Units):
"The following parameters are missing examples :( \n %s" % "The following parameters are missing examples :( \n %s" %
[ p["name"] for p in params_missing_examples ] [ p["name"] for p in params_missing_examples ]
) )
endpoint["responses"].append(ok_res)
endpoints.append(endpoint) endpoints.append(endpoint)
return { return {
"base": api.get("basePath"), "base": api.get("basePath"),
"group": group_name, "group": group_name,