DEV: Add API docs for uploads and API doc watcher (#15387)

This commit adds API documentation for the new upload
endpoints related to direct + multipart external uploads.

Also included is a rake task which watches the files in
the spec/requests/api directory and calls a script file
(spec/regenerate_swagger_docs) whenever one changes. This
script runs rake rswag:specs:swaggerize and then copies
the openapi.yml file over to the discourse_api_docs repo
directory, and hits a script there to convert the YML to
JSON so the API docs are refreshed while the server is
still running. This makes the loop of making a doc change
and seeing it in the local server much faster.

The rake task is rake autospec:swagger

spec/requests/api/schemas/json/upload_abort_multipart_request.json

@@ -0,0 +1,13 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "external_upload_identifier": {
+      "type": "string",
+      "description": "The identifier of the multipart upload in the external storage provider. This is the multipart upload_id in AWS S3.",
+      "example": "84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ"
+    }
+  },
+  "required": [
+    "external_upload_identifier"
+  ]
+}

spec/requests/api/schemas/json/upload_batch_presign_multipart_parts_request.json

@@ -0,0 +1,19 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "part_numbers": {
+      "type": "array",
+      "description": "The part numbers to generate the presigned URLs for, must be between 1 and 10000.",
+      "example": [1, 2, 3]
+    },
+    "unique_identifier": {
+      "type": "string",
+      "description": "The unique identifier returned in the original /create-multipart request.",
+      "example": "66e86218-80d9-4bda-b4d5-2b6def968705"
+    }
+  },
+  "required": [
+    "part_numbers",
+    "unique_identifier"
+  ]
+}

spec/requests/api/schemas/json/upload_batch_presign_multipart_parts_response.json

@@ -0,0 +1,15 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "presigned_urls": {
+      "type": "object",
+      "description": "The presigned URLs for each part number, which has the part numbers as keys.",
+      "example": {
+        "1": "https://discourse-martin-uploads-test.s3.us-east-2.amazonaws.com/temp/uploads/default/123abc/123abc.jpg?partNumber=1&uploadId=123456abcd&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test&X-Amz-Date=20211222T012336Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123"
+      }
+    }
+  },
+  "required": [
+    "presigned_urls"
+  ]
+}

spec/requests/api/schemas/json/upload_complete_external_upload_request.json

@@ -0,0 +1,28 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "unique_identifier": {
+      "type": "string",
+      "example": "66e86218-80d9-4bda-b4d5-2b6def968705",
+      "description": "The unique identifier returned in the original /generate-presigned-put request."
+    },
+    "for_private_message": {
+      "type": "string",
+      "example": "true",
+      "description": "Optionally set this to true if the upload is for a private message."
+    },
+    "for_site_setting": {
+      "type": "string",
+      "example": "true",
+      "description": "Optionally set this to true if the upload is for a site setting."
+    },
+    "pasted": {
+      "type": "string",
+      "example": "true",
+      "description": "Optionally set this to true if the upload was pasted into the upload area. This will convert PNG files to JPEG."
+    }
+  },
+  "required": [
+    "unique_identifier"
+  ]
+}

spec/requests/api/schemas/json/upload_complete_multipart_request.json

@@ -0,0 +1,28 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "unique_identifier": {
+      "type": "string",
+      "example": "66e86218-80d9-4bda-b4d5-2b6def968705",
+      "description": "The unique identifier returned in the original /create-multipart request."
+    },
+    "parts": {
+      "type": "array",
+      "example": [
+        {
+          "part_number": 1,
+          "etag": "0c376dcfcc2606f4335bbc732de93344"
+        },
+        {
+          "part_number": 2,
+          "etag": "09ert8cfcc2606f4335bbc732de91122"
+        }
+      ],
+      "description": "All of the part numbers and their corresponding ETags that have been uploaded must be provided."
+    }
+  },
+  "required": [
+    "unique_identifier",
+    "parts"
+  ]
+}

spec/requests/api/schemas/json/upload_create_multipart_request.json

@@ -0,0 +1,39 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "upload_type": {
+      "type": "string",
+      "enum": [
+        "avatar",
+        "profile_background",
+        "card_background",
+        "custom_emoji",
+        "composer"
+      ]
+    },
+    "file_name": {
+      "type": "string",
+      "example": "IMG_2021.jpeg"
+    },
+    "file_size": {
+      "type": "integer",
+      "description": "File size should be represented in bytes.",
+      "example": 4096
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sha1-checksum": {
+          "type": "string",
+          "description": "The SHA1 checksum of the upload binary blob. Optionally be provided and serves as an additional security check when later processing the file in complete-external-upload endpoint."
+        }
+      }
+    }
+  },
+  "required": [
+    "upload_type",
+    "file_name",
+    "file_size"
+  ]
+}

spec/requests/api/schemas/json/upload_create_multipart_response.json

@@ -0,0 +1,25 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "key": {
+      "type": "string",
+      "description": "The path of the temporary file on the external storage service.",
+      "example": "temp/site/uploads/default/12345/67890.jpg"
+    },
+    "external_upload_identifier": {
+      "type": "string",
+      "description": "The identifier of the multipart upload in the external storage provider. This is the multipart upload_id in AWS S3.",
+      "example": "84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ"
+    },
+    "unique_identifier": {
+      "type": "string",
+      "description": "A unique string that identifies the external upload. This must be stored and then sent in the /complete-multipart and /batch-presign-multipart-parts endpoints.",
+      "example": "66e86218-80d9-4bda-b4d5-2b6def968705"
+    }
+  },
+  "required": [
+    "external_upload_identifier",
+    "key",
+    "unique_identifier"
+  ]
+}

spec/requests/api/schemas/json/upload_generate_presigned_put_request.json

@@ -0,0 +1,39 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "avatar",
+        "profile_background",
+        "card_background",
+        "custom_emoji",
+        "composer"
+      ]
+    },
+    "file_name": {
+      "type": "string",
+      "example": "IMG_2021.jpeg"
+    },
+    "file_size": {
+      "type": "integer",
+      "description": "File size should be represented in bytes.",
+      "example": 4096
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sha1-checksum": {
+          "type": "string",
+          "description": "The SHA1 checksum of the upload binary blob. Optionally be provided and serves as an additional security check when later processing the file in complete-external-upload endpoint."
+        }
+      }
+    }
+  },
+  "required": [
+    "type",
+    "file_name",
+    "file_size"
+  ]
+}

spec/requests/api/schemas/json/upload_generate_presigned_put_response.json

@@ -0,0 +1,21 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "key": {
+      "type": "string",
+      "description": "The path of the temporary file on the external storage service.",
+      "example": "temp/site/uploads/default/12345/67890.jpg"
+    },
+    "url": {
+      "type": "string",
+      "description": "A presigned PUT URL which must be used to upload the file binary blob to.",
+      "example": "https://file-uploads.s3.us-west-2.amazonaws.com/temp/site/uploads/default/123/456.jpg?x-amz-acl=private&x-amz-meta-sha1-checksum=sha1&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AAAAus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20211221T011246Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=12345678"
+    },
+    "unique_identifier": {
+      "type": "string",
+      "description": "A unique string that identifies the external upload. This must be stored and then sent in the /complete-external-upload endpoint to complete the direct upload.",
+      "example": "66e86218-80d9-4bda-b4d5-2b6def968705"
+    }
+  }
+}
+