Fix example Content-Type for /media/upload request

Fixes https://github.com/matrix-org/matrix-doc/issues/1770

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.

changelogs/client_server/newsfragments/2041.clarification

@@ -0,0 +1 @@
+Fix example ``Content-Type`` for ``/media/upload`` request.

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" % (
+                "req"] = "%s %s%s HTTP/1.1\nContent-Type: %s\n\n%s" % (
-                method.upper(), path_template, query_string, example_body
+                method.upper(), path_template, query_string, example_mime, example_body
             )
         else:
             endpoint["example"]["req"] = "%s %s%s HTTP/1.1\n\n" % (