From 62890d21b25016dc008a5cc2e2f993ee3a0873ab Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Mon, 27 May 2019 23:08:02 -0600
Subject: [PATCH] Fix example Content-Type for /media/upload request

Fixes https://github.com/matrix-org/matrix-doc/issues/1770
---
 api/client-server/content-repo.yaml                   | 11 ++++++-----
 .../client_server/newsfragments/2041.clarification    |  1 +
 scripts/templating/matrix_templates/units.py          |  9 +++++++--
 3 files changed, 14 insertions(+), 7 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/2041.clarification

diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml
index 07df18fe1..4460bb69d 100644
--- a/api/client-server/content-repo.yaml
+++ b/api/client-server/content-repo.yaml
@@ -41,7 +41,7 @@ paths:
           name: Content-Type
           type: string
           description: The content type of the file being uploaded
-          x-example: "Content-Type: audio/mpeg"
+          x-example: "Content-Type: application/pdf"
         - in: query
           type: string
           x-example: "War and Peace.pdf"
@@ -51,6 +51,7 @@ paths:
           name: "<content>"
           description: The content to be uploaded.
           required: true
+          x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
           schema:
             type: string
             example: "<bytes>"
@@ -103,7 +104,7 @@ paths:
           default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to 
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
             true if not provided.
       responses:
         200:
@@ -158,7 +159,7 @@ paths:
           default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to 
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
             true if not provided.
       responses:
         200:
@@ -228,7 +229,7 @@ paths:
           default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to 
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
             true if not provided.
       responses:
         200:
@@ -330,7 +331,7 @@ paths:
               m.upload.size:
                 type: integer
                 format: int64
-                description: |- 
+                description: |-
                   The maximum size an upload can be in bytes.
                   Clients SHOULD use this as a guide when uploading content.
                   If not listed or null, the size limit should be treated as unknown.
diff --git a/changelogs/client_server/newsfragments/2041.clarification b/changelogs/client_server/newsfragments/2041.clarification
new file mode 100644
index 000000000..39bbddb5a
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2041.clarification
@@ -0,0 +1 @@
+Fix example ``Content-Type`` for ``/media/upload`` request.
diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py
index 466110f81..d4745e4d6 100644
--- a/scripts/templating/matrix_templates/units.py
+++ b/scripts/templating/matrix_templates/units.py
@@ -521,6 +521,7 @@ class MatrixUnits(Units):
         path_template = path
         example_query_params = []
         example_body = ""
+        example_mime = "application/json"
         for param in endpoint_swagger.get("parameters", []):
             # even body params should have names, otherwise the active docs don't work.
             param_name = param["name"]
@@ -533,6 +534,10 @@ class MatrixUnits(Units):
                     example_body = get_example_for_param(param)
                     continue
 
+                if param_loc == "header":
+                    if param["name"] == "Content-Type" and param["x-example"]:
+                        example_mime = param["x-example"]
+
                 # description
                 desc = param.get("description", "")
                 if param.get("required"):
@@ -610,8 +615,8 @@ class MatrixUnits(Units):
             example_query_params)
         if example_body:
             endpoint["example"][
-                "req"] = "%s %s%s HTTP/1.1\nContent-Type: application/json\n\n%s" % (
-                method.upper(), path_template, query_string, example_body
+                "req"] = "%s %s%s HTTP/1.1\nContent-Type: %s\n\n%s" % (
+                method.upper(), path_template, query_string, example_mime, example_body
             )
         else:
             endpoint["example"]["req"] = "%s %s%s HTTP/1.1\n\n" % (