Merge pull request #31 from matrix-org/daniel/specformat

Show all responses, not just the successful one

templating/matrix_templates/templates/http-api.tmpl

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

templating/matrix_templates/units.py

@@ -116,7 +116,8 @@ class MatrixUnits(Units):
                     "res_tables": [],
                     "example": {
                         "req": "",
-                        "res": ""
+                        "responses": [],
+                        "good_response": ""
                     }
                 }
                 self.log(".o.O.o. Endpoint: %s %s" % (method, path))
@@ -177,11 +178,19 @@ class MatrixUnits(Units):
                         endpoint["req_param_by_loc"][p["loc"]] = []
                     endpoint["req_param_by_loc"][p["loc"]].append(p)
 
-                # add example response if it has one
-                res = single_api["responses"][200]  # get the 200 OK response
-                endpoint["example"]["res"] = res.get("examples", {}).get(
-                    "application/json", ""
-                )
+                good_response = None
+                for code, res in single_api.get("responses", {}).items():
+                    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,
+                        })
+
                 # 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 = [
@@ -216,22 +225,25 @@ class MatrixUnits(Units):
                     )
 
                 # 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_tables"].append({
-                        "title": None,
-                        "rows": [{
-                            "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"])
-                    for table in res_tables:
-                        if "no-table" not in table:
-                            endpoint["res_tables"].append(table)
+                if good_response:
+                    res_type = Units.prop(good_response, "schema/type")
+                    if res_type and res_type not in ["object", "array"]:
+                        # response is a raw string or something like that
+                        endpoint["res_tables"].append({
+                            "title": None,
+                            "rows": [{
+                                "key": good_response["schema"].get("name", ""),
+                                "type": res_type,
+                                "desc": res.get("description", "")
+                            }]
+                        })
+                    elif res_type and Units.prop(good_response, "schema/properties"):
+                        # response is an object:
+                        schema = good_response["schema"]
+                        res_tables = get_json_schema_object_fields(schema)
+                        for table in res_tables:
+                            if "no-table" not in table:
+                                endpoint["res_tables"].append(table)
 
                 endpoints.append(endpoint)