From f6c98f41e978828f650aa5bb60d964ae55944667 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Mon, 1 Jun 2015 15:26:48 +0100
Subject: [PATCH] Use table subsections for param locations instead of an extra
 column.

---
 api/client-server/v1/profile.yaml             |  2 +-
 .../matrix_templates/templates/http-api.tmpl  | 17 ++++----
 templating/matrix_templates/units.py          | 41 ++++++-------------
 3 files changed, 24 insertions(+), 36 deletions(-)

diff --git a/api/client-server/v1/profile.yaml b/api/client-server/v1/profile.yaml
index ff25cae10..58f9e108d 100644
--- a/api/client-server/v1/profile.yaml
+++ b/api/client-server/v1/profile.yaml
@@ -107,7 +107,7 @@ paths:
             type: object
             example: |-
               {
-                "avatar_url": "mxc:/matrix.org/wefh34uihSDRGhw34"
+                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
               }
             properties:
               avatar_url:
diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl
index b8dcace59..a38e25233 100644
--- a/templating/matrix_templates/templates/http-api.tmpl
+++ b/templating/matrix_templates/templates/http-api.tmpl
@@ -8,14 +8,17 @@
 
 Request format:
 
-================== ================= =========== ===============================
-   Parameter         Param Location  Param Type          Description
-================== ================= =========== ===============================
-{% for param in endpoint.req_params -%}
-{{param.name}}{{param.loc|indent(19-param.name|length)}}{{param.type|indent(37-19-
-param.loc|length)}}{{param.desc|indent(12-param.type|length)|wrap(31)|indent_block(49)}}
+================== ================= ===========================================
+   Parameter            Value                        Description
+================== ================= ===========================================
+{% for loc in endpoint.req_param_by_loc -%}
+**{{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 %}
+================== ================= ===========================================
 
 Example request::
 
diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py
index 4dcd0c33c..ed39fc08e 100644
--- a/templating/matrix_templates/units.py
+++ b/templating/matrix_templates/units.py
@@ -112,9 +112,6 @@ class MatrixUnits(Units):
                     "requires_auth": "security" in single_api,
                     "rate_limited": 429 in single_api.get("responses", {}),
                     "req_params": [],
-                    "responses": [
-                    # { code: 200, [ {row_info} ]}
-                    ],
                     "example": {
                         "req": "",
                         "res": ""
@@ -164,35 +161,24 @@ class MatrixUnits(Units):
                     for key in json_body:
                         endpoint["req_params"].append({
                             "name": key,
-                            "loc": "JSON",
+                            "loc": "JSON body",
                             "type": json_body[key]["type"],
                             "desc": json_body[key]["description"]
                         })
+                # endfor[param]
 
-                # add main response format first.
-                res200 = single_api["responses"][200]
-                res200params = []
-                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
+                # group params by location to ease templating
+                endpoint["req_param_by_loc"] = {
+                    #   path: [...], query: [...], body: [...]
                 }
+                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
-                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", ""
                 )
                 # 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" %
                         [ p["name"] for p in params_missing_examples ]
                     )
-                endpoint["responses"].append(ok_res)
-
                 endpoints.append(endpoint)
+
         return {
             "base": api.get("basePath"),
             "group": group_name,