From d9f0acac58c7d881a8bdbc2df68e425de9344873 Mon Sep 17 00:00:00 2001
From: Mathis <avnyr@yidhra.fr>
Date: Thu, 17 Oct 2024 14:56:06 +0200
Subject: [PATCH] Enhance file upload endpoint in FilesController

Added detailed Swagger annotations including headers, body schema, and operation summary to improve API documentation for the file upload endpoint. These updates provide clear information about the expected input parameters for better usability and integration.
---
 .../backend/src/app/files/files.controller.ts | 56 ++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/apps/backend/src/app/files/files.controller.ts b/apps/backend/src/app/files/files.controller.ts
index 9e60419..9c65af7 100644
--- a/apps/backend/src/app/files/files.controller.ts
+++ b/apps/backend/src/app/files/files.controller.ts
@@ -23,13 +23,67 @@ import {
 import { CreateFileTypeDto } from "apps/backend/src/app/files/files.dto";
 import { AdminGuard, InsertAdminState } from "../auth/auth.guard";
 import { FilesService } from "./files.service";
-import { ApiBearerAuth, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth, ApiBody, ApiConsumes,
+	ApiHeaders, ApiOperation,
+	ApiSecurity,
+	ApiTags
+} from '@nestjs/swagger';
 
 @ApiTags('Files')
 @Controller("files")
 export class FilesController {
 	constructor(private readonly filesService: FilesService) {}
 
+	@ApiOperation({ summary: "Uploader un fichier"})
+	@ApiConsumes("application/octet-stream")
+	@ApiBody({
+		schema: {
+			type: 'string',
+			format: 'binary'
+		}
+	})
+	@ApiHeaders([
+		{
+			name: "file_name",
+			description: "Nom du fichier",
+			example: "Logo marianne",
+			allowEmptyValue: false,
+			required: true
+		},
+		{
+			name: "group_id",
+			description: "Groupe de fichier optionnel",
+			example: "dfd0fbb1-2bf3-4dbe-b86d-89b1bff5106c",
+			allowEmptyValue: true
+		},
+		{
+			name: "machine_id",
+			description: "Identifiant(s) de machine(s)",
+			example: ["dfd0fbb1-2bf3-4dbe-b86d-89b1bff5106c", "dfd0fbb1-2bf3-4dbe-b86d-89b1bff5106c"],
+			allowEmptyValue: false,
+			required: true,
+		},
+		{
+			name: "uploaded_by",
+			description: "Pseudonyme requis mais au choix.",
+			example: "Jean Paul",
+			allowEmptyValue: false,
+			required: true,
+		},
+		{
+			name: "is_documentation",
+			description: "Admin uniquement, défini le fichier comme étant une documentation",
+			enum: ["true", "false"],
+			allowEmptyValue: false,
+		},
+		{
+			name: "is_restricted",
+			description: "Admin uniquement, rend impossible l'écrasement d'un fichier (non implémenté pour l'instant)",
+			enum: ["true", "false"],
+			allowEmptyValue: false,
+		},
+	])
 	@HttpCode(HttpStatus.OK)
 	@UseGuards(InsertAdminState)
 	@Post("new")