docs: file-upload-download

docs/.vitepress/config.ts

@@ -29,6 +29,7 @@ export default defineConfig({
           { text: 'Express Integration', link: '/guide/express-integration' }, // with Request validation
           { text: 'API Testing', link: '/guide/api-testing' },
           { text: 'Authentication', link: '/guide/authentication' },
+          { text: 'File Upload/Download', link: '/guide/file-upload-download' },
         ]
       },
       {

docs/guide/file-upload-download.md

@@ -0,0 +1,106 @@
+# File Upload and Download
+
+On this page, we will learn how to generate OpenAPI Spec for file upload and download.
+
+## File Upload
+
+You can describe the file upload schema with JSDoc tag `@mediaType multipart/form-data`.
+:::tip
+Also, you can use other media types such as `image/png` or `application/pdf`.
+See OpenAPI File Upload Documentation [here](https://swagger.io/docs/specification/describing-request-body/file-upload/).
+:::
+
+
+```ts{6-9}
+export type FileApiSpec = Tspec.DefineApiSpec<{
+  paths: {
+    '/files/upload': {
+      post: {
+        summary: 'Upload File',
+        /** @mediaType multipart/form-data */
+        body: {
+          file: Tspec.BinaryString;
+        },
+        responses: { 200: { fileName: string } },
+      },
+    },
+  },
+}>;
+```
+
+:::details Generated OpenAPI Spec  
+```yaml{6-15}
+paths:
+  "/files/upload":
+    post:
+      operationId: FileApiSpec_post_/files/upload
+      summary: Upload File
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  fileName:
+                    type: string
+```
+:::
+
+Then, you can see the file upload form in Swagger UI.
+![File Upload](/assets/images/file-upload.png)
+
+
+## File Download
+
+You can describe the file download schema with JSDoc tag `@mediaType application/octet-stream`.
+:::tip
+Also, you can use other media types such as `image/png` or `application/pdf`.
+See OpenAPI Describing Responses Documentation [here](https://swagger.io/docs/specification/describing-responses/#file).
+:::
+
+```ts{6-9}
+export type FileApiSpec = Tspec.DefineApiSpec<{
+  paths: {
+    '/files/download': {
+      get: {
+        summary: 'Download File',
+        responses: {
+          /** @mediaType application/octet-stream */
+          200: Tspec.BinaryString
+        },
+      },
+    },
+  },
+}>;
+```
+
+:::details Generated OpenAPI Spec  
+```yaml{8-12}
+paths:
+  "/files/download":
+    get:
+      operationId: FileApiSpec_get_/files/download
+      summary: Download File
+      responses:
+        '200':
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+```
+:::
+
+Then, you can download the file in Swagger UI.
+![File Download](/assets/images/file-download.png)