docs: document 200 OK response for upload file API when file exists (#21071)

Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>

coderd/apidoc/docs.go

@@ -1290,8 +1290,14 @@ const docTemplate = `{
                     }
                 ],
                 "responses": {
+                    "200": {
+                        "description": "Returns existing file if duplicate",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.UploadResponse"
+                        }
+                    },
                     "201": {
-                        "description": "Created",
+                        "description": "Returns newly created file",
                         "schema": {
                             "$ref": "#/definitions/codersdk.UploadResponse"
                         }

coderd/apidoc/swagger.json

@@ -1116,8 +1116,14 @@
 					}
 				],
 				"responses": {
+					"200": {
+						"description": "Returns existing file if duplicate",
+						"schema": {
+							"$ref": "#/definitions/codersdk.UploadResponse"
+						}
+					},
 					"201": {
-						"description": "Created",
+						"description": "Returns newly created file",
 						"schema": {
 							"$ref": "#/definitions/codersdk.UploadResponse"
 						}

coderd/files.go

@@ -41,7 +41,8 @@ const (
 // @Tags Files
 // @Param Content-Type header string true "Content-Type must be `application/x-tar` or `application/zip`" default(application/x-tar)
 // @Param file formData file true "File to be uploaded. If using tar format, file must conform to ustar (pax may cause problems)."
-// @Success 201 {object} codersdk.UploadResponse
+// @Success 200 {object} codersdk.UploadResponse "Returns existing file if duplicate"
+// @Success 201 {object} codersdk.UploadResponse "Returns newly created file"
 // @Router /files [post]
 func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()

docs/reference/api/files.md

@@ -31,7 +31,7 @@ file: string
 
 ### Example responses
 
-> 201 Response
+> 200 Response
 
 ```json
 {
@@ -41,9 +41,10 @@ file: string
 
 ### Responses
 
-| Status | Meaning                                                      | Description | Schema                                                       |
-|--------|--------------------------------------------------------------|-------------|--------------------------------------------------------------|
-| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created     | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
+| Status | Meaning                                                      | Description                        | Schema                                                       |
+|--------|--------------------------------------------------------------|------------------------------------|--------------------------------------------------------------|
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)      | Returns existing file if duplicate | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
+| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Returns newly created file         | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
 
 To perform this operation, you must be authenticated. [Learn more](authentication.md).