Update from code changes: document OpenAPI file uploads

api-playground/openapi-setup.mdx

@@ -78,6 +78,42 @@
 
 If your API has endpoints that exist at different URLs, you can [override the `servers` field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation.
 
+### Configure file uploads
+
+For OpenAPI 3.1 specifications, define a file upload as a string schema with a binary `contentMediaType`. The API playground recognizes the field as a file input and sends it as part of a `multipart/form-data` request.
+
+Use this configuration when an endpoint accepts a file inside a multipart request. You can also use `contentEncoding` to describe how the file content encodes. A `contentEncoding` value without a binary `contentMediaType` remains a text field. For base64-encoded files, set `contentEncoding` to `base64` or `base64url`. The API playground treats either value as a base64 file. For other values or no value, the API playground uses binary file handling.
+
+```json
+{
+  "paths": {
+    "/imports": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "contentMediaType": "application/octet-stream"
+                  }
+                },
+                "required": ["file"]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+You can use binary media types such as `application/octet-stream`, images, audio, video, PDFs, and archives. The API playground does not treat structured media types such as `application/json` as file uploads. The older `format: "binary"` and `format: "base64"` values remain supported.
+
 ### Specify authentication
 
 To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI specification. The API descriptions and API playground add authentication fields based on the security configurations in your OpenAPI specification.
@@ -147,7 +183,7 @@
 }
 ```
 
 The `x-default` extension supports `apiKey` and `http` bearer security scheme types. The value appears as the default input in the playground's authentication fields. Prefill for security schemes is unconditional and does not require any additional configuration.
 
 Use `x-default` on other schema properties in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. Unlike security schemes, prefill for non-security-scheme properties only takes effect when you set [`api.examples.prefill`](/organize/settings-api) to `true` in your [`docs.json`](/api-playground/overview#example-configuration).
 

es/api-playground/openapi-setup.mdx

@@ -84,6 +84,44 @@ El área de pruebas de la API usa estas URL de servidor para determinar adónde
 
 Si tu API tiene endpoints que se encuentran en distintas URL, puedes [sobrescribir el campo `servers`](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) para una ruta u operación determinada.
 
+<div id="configure-file-uploads">
+  ### Configura cargas de archivos
+</div>
+
+En las especificaciones OpenAPI 3.1, define una carga de archivo como un esquema de tipo string con un `contentMediaType` binario. El playground de la API reconoce el campo como un selector de archivos y lo envía como parte de una solicitud `multipart/form-data`.
+
+Usa esta configuración cuando un endpoint acepte un archivo dentro de una solicitud multipart. También puedes usar `contentEncoding` para describir cómo se codifica el contenido del archivo. Un valor `contentEncoding` sin un `contentMediaType` binario sigue siendo un campo de texto. Para archivos codificados en base64, establece `contentEncoding` en `base64` o `base64url`. El playground trata ambos valores como un archivo base64. Para otros valores o cuando no se define ningún valor, el playground usa el procesamiento de archivos binarios.
+
+```json
+{
+  "paths": {
+    "/imports": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "contentMediaType": "application/octet-stream"
+                  }
+                },
+                "required": ["file"]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Puedes usar tipos MIME binarios como `application/octet-stream`, imágenes, audio, video, PDF y archivos comprimidos. El playground de la API no trata los tipos estructurados como `application/json` como cargas de archivos. Los valores anteriores `format: "binary"` y `format: "base64"` siguen siendo compatibles.
+
 <div id="specify-authentication">
   ### Especificar la autenticación
 </div>

fr/api-playground/openapi-setup.mdx

@@ -84,6 +84,44 @@ Le bac à sable de l’API utilise ces URL de serveur pour déterminer où envoy
 
 Si votre API comporte des points de terminaison accessibles à différentes URL, vous pouvez [surcharger le champ `servers`](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) pour un chemin ou une opération donnés.
 
+<div id="configure-file-uploads">
+  ### Configurer les téléversements de fichiers
+</div>
+
+Dans les spécifications OpenAPI 3.1, définissez un téléversement de fichier comme un schéma de type string avec un `contentMediaType` binaire. Le playground de l’API reconnaît le champ comme un sélecteur de fichier et l’envoie dans une requête `multipart/form-data`.
+
+Utilisez cette configuration lorsqu’un endpoint accepte un fichier dans une requête multipart. Vous pouvez également utiliser `contentEncoding` pour décrire le codage du contenu du fichier. Une valeur `contentEncoding` sans `contentMediaType` binaire reste un champ texte. Pour les fichiers encodés en base64, définissez `contentEncoding` sur `base64` ou `base64url`. Le playground traite ces deux valeurs comme un fichier base64. Pour les autres valeurs ou en l’absence de valeur, le playground utilise le traitement des fichiers binaires.
+
+```json
+{
+  "paths": {
+    "/imports": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "contentMediaType": "application/octet-stream"
+                  }
+                },
+                "required": ["file"]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Vous pouvez utiliser des types MIME binaires tels que `application/octet-stream`, les images, l’audio, la vidéo, les PDF et les archives. Le playground de l’API ne traite pas les types structurés tels que `application/json` comme des téléversements de fichiers. Les anciennes valeurs `format: "binary"` et `format: "base64"` restent prises en charge.
+
 <div id="specify-authentication">
   ### Spécifier l’authentification
 </div>

zh/api-playground/openapi-setup.mdx

@@ -1,6 +1,6 @@
 ---
 title: "OpenAPI 设置"
-description: "从 OpenAPI 规范文件生成交互式 API 文档，自动创建端点页面、请求构建器和导航结构。"
+description: "从 OpenAPI 3.0 和 3.1 规范文件生成交互式 API 文档，自动创建端点页面、请求构建器和导航结构，并配置身份验证、服务器 URL、请求参数与文件上传，帮助你快速发布完整且易于测试的 API 参考文档。了解如何设置规范文件、服务器地址、安全方案和文件字段。"
 keywords: ["OpenAPI", "API 规范", "Swagger"]
 ---
 
@@ -84,6 +84,44 @@ API playground 会使用这些服务器 URL 来确定请求的发送目标。如
 
 如果你的 API 的端点分布在不同的 URL 下，你可以为特定路径或操作[覆盖 `servers` 字段](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers)。
 
+<div id="configure-file-uploads">
+  ### 配置文件上传
+</div>
+
+对于 OpenAPI 3.1 规范，请将文件上传定义为带有二进制 `contentMediaType` 的 string 类型 schema。API playground 会将该字段识别为文件选择器，并将其作为 `multipart/form-data` 请求的一部分发送。
+
+当端点在 multipart 请求中接收文件时，请使用此配置。你也可以使用 `contentEncoding` 描述文件内容的编码方式。没有二进制 `contentMediaType` 的 `contentEncoding` 值仍会被视为文本字段。对于使用 base64 编码的文件，请将 `contentEncoding` 设置为 `base64` 或 `base64url`。API playground 会将这两个值识别为 base64 文件。对于其他值或未设置值的情况，API playground 会按二进制方式处理文件。
+
+```json
+{
+  "paths": {
+    "/imports": {
+      "post": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "contentMediaType": "application/octet-stream"
+                  }
+                },
+                "required": ["file"]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+你可以使用 `application/octet-stream`、图像、音频、视频、PDF 和归档文件等二进制媒体类型。API playground 不会将 `application/json` 等结构化媒体类型识别为文件上传。旧版 `format: "binary"` 和 `format: "base64"` 值仍受支持。
+
 <div id="specify-authentication">
   ### 指定身份验证
 </div>