Add Swagger metadata to DTOs and controllers

Enhanced API documentation by adding Swagger decorators like @ApiProperty, @ApiTags, and @ApiBearerAuth to DTOs and controllers. This will improve clarity and usability of the API for developers using Swagger.

apps/backend/src/app/app.controller.ts

@@ -1,8 +1,10 @@
 import { Controller, Get } from "@nestjs/common";
 
 import { AppService } from "./app.service";
+import { ApiTags } from '@nestjs/swagger';
 
 @Controller()
+@ApiTags("useless")
 export class AppController {
 	constructor(private readonly appService: AppService) {}
 

apps/backend/src/app/auth/auth.controller.ts

@@ -13,7 +13,9 @@ import {
 import { SignInDto, SignUpDto } from "apps/backend/src/app/auth/auth.dto";
 import { AuthService } from "apps/backend/src/app/auth/auth.service";
 import { UserGuard } from "./auth.guard";
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
 
+@ApiTags('User authentification')
 @Controller("auth")
 export class AuthController {
 	constructor(private readonly authService: AuthService) {}
@@ -33,6 +35,7 @@ export class AuthController {
 		return this.authService.doLogin(dto);
 	}
 	//GET me -- Get current user data via jwt
+	@ApiBearerAuth()
 	@HttpCode(HttpStatus.OK)
 	@Get("me")
 	@UseGuards(UserGuard)
@@ -46,6 +49,7 @@ export class AuthController {
 		return userData;
 	}
 	//DELETE me
+	@ApiBearerAuth()
 	@HttpCode(HttpStatus.FOUND)
 	@Delete("me")
 	@UseGuards(UserGuard)

apps/backend/src/app/auth/auth.dto.ts

@@ -6,6 +6,7 @@ import {
 	MaxLength,
 	MinLength,
 } from "class-validator";
+import { ApiProperty } from '@nestjs/swagger';
 
 export class SignUpDto {
 	/*
@@ -22,11 +23,17 @@ export class SignUpDto {
   lastName: string;
   **/
 
+	@ApiProperty({
+		example: 'jean@paul.fr',
+	})
 	@MaxLength(32)
 	@IsEmail()
 	@IsNotEmpty()
 	email: string;
 
+	@ApiProperty({
+		example: 'zSEs-6ze$',
+	})
 	@IsString()
 	@IsNotEmpty()
 	@IsStrongPassword({
@@ -36,12 +43,16 @@ export class SignUpDto {
 }
 
 export class SignInDto {
-	@MaxLength(32)
+	@MaxLength(32)@ApiProperty({
+		example: 'jean@paul.fr',
+	})
 	@IsEmail()
 	@IsNotEmpty()
 	email: string;
 
-	@IsString()
+	@IsString()@ApiProperty({
+		example: 'zSEs-6ze$',
+	})
 	@IsNotEmpty()
 	@IsStrongPassword({
 		minLength: 6,

apps/backend/src/app/authors/authors.controller.ts

@@ -11,7 +11,9 @@ import {
 } from "@nestjs/common";
 import { AdminGuard } from "apps/backend/src/app/auth/auth.guard";
 import { AuthorsService } from "apps/backend/src/app/authors/authors.service";
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
 
+@ApiTags('File authors')
 @Controller("authors")
 export class AuthorsController {
 	constructor(private readonly authorService: AuthorsService) {}
@@ -25,8 +27,8 @@ export class AuthorsController {
 		return await this.authorService.find(limit, offset, search);
 	}
 
-	//TODO DTO
-
+	//TODO Refactor
+	@ApiBearerAuth()
 	@UseGuards(AdminGuard)
 	@Delete(":autor")
 	async deleteAuthor(@Param("author") author: string) {

apps/backend/src/app/files/files.controller.ts

@@ -23,7 +23,9 @@ 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';
 
+@ApiTags('Files')
 @Controller("files")
 export class FilesController {
 	constructor(private readonly filesService: FilesService) {}
@@ -129,6 +131,7 @@ export class FilesController {
 		return await this.filesService.getAllFilesTypes();
 	}
 
+	@ApiBearerAuth()
 	@HttpCode(HttpStatus.CREATED)
 	@UseGuards(AdminGuard)
 	@Post("types/new")
@@ -136,6 +139,7 @@ export class FilesController {
 		return await this.filesService.createFileType(body.name, body.mime);
 	}
 
+	@ApiBearerAuth()
 	@HttpCode(HttpStatus.ACCEPTED)
 	@UseGuards(AdminGuard)
 	@Delete("types/:typeId")
@@ -149,6 +153,7 @@ export class FilesController {
 		return await this.filesService.get(fileId);
 	}
 
+	@ApiBearerAuth()
 	@HttpCode(HttpStatus.OK)
 	@UseGuards(AdminGuard)
 	@Delete(":fileId")

apps/backend/src/app/files/files.dto.ts

@@ -1,27 +1,26 @@
 import { DefaultValuePipe } from "@nestjs/common";
 import { IsUUID, MaxLength, MinLength } from "class-validator";
-
-export class CreateFilesDto {
-	@MaxLength(128)
-	@MinLength(4)
-	fileName: string;
-
-	@MaxLength(64)
-	@MinLength(2)
-	uploadedBy: string;
-
-	isDocumentation?: boolean;
-	isRestricted?: boolean;
-
-	@IsUUID()
-	groupId: string;
-}
+import { ApiBearerAuth, ApiProperty } from '@nestjs/swagger';
 
 export class CreateFileTypeDto {
+	@ApiProperty({
+		description: "Admin uniquement, nom d'affichage.",
+		examples: [
+			".scad",
+			"jpg"
+		]
+	})
 	@MaxLength(128)
 	@MinLength(3)
 	name: string;
 
+	@ApiProperty({
+		description: "Admin uniquement, Multipurpose Internet Mail Extensions (MIME)",
+		examples: [
+			"application/x-openscad",
+			"image/jpeg"
+		]
+	})
 	@MaxLength(64)
 	@MinLength(4)
 	mime: string;

apps/backend/src/app/groups/groups.controller.ts

@@ -14,7 +14,9 @@ import { AdminGuard } from "apps/backend/src/app/auth/auth.guard";
 import { CreateGroupDto } from "apps/backend/src/app/groups/groups.dto";
 import { ISearchQuery } from "apps/backend/src/app/groups/groups.types";
 import { GroupsService } from "./groups.service";
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
 
+@ApiTags('File groups')
 @Controller("groups")
 export class GroupsController {
 	constructor(private readonly groupsService: GroupsService) {}
@@ -33,6 +35,7 @@ export class GroupsController {
 		return await this.groupsService.newGroup(body.groupName);
 	}
 
+	@ApiBearerAuth()
 	@UseGuards(AdminGuard)
 	@Delete(":groupId")
 	async deleteGroup(@Param("groupId") groupId: string) {

apps/backend/src/app/groups/groups.dto.ts

@@ -1,6 +1,11 @@
 import { IsString, MaxLength, MinLength } from "class-validator";
+import { ApiProperty } from '@nestjs/swagger';
 
 export class CreateGroupDto {
+	@ApiProperty({
+		description: "Nom unique.",
+		example: "Numérique en communs"
+	})
 	@IsString()
 	@MinLength(4)
 	@MaxLength(64)

apps/backend/src/app/machines/machines.controller.ts

@@ -19,7 +19,9 @@ import {
 	TypeDto,
 } from "apps/backend/src/app/machines/machines.dto";
 import { MachinesService } from "apps/backend/src/app/machines/machines.service";
+import { ApiTags } from '@nestjs/swagger';
 
+@ApiTags('Machines')
 @Controller("machines")
 export class MachinesController {
 	constructor(private readonly machineService: MachinesService) {}

apps/backend/src/app/machines/machines.dto.ts

@@ -1,16 +1,27 @@
 import { IsUUID, MaxLength, MinLength } from "class-validator";
+import { ApiProperty } from '@nestjs/swagger';
 
 export class CreateMachineDto {
+	@ApiProperty({
+		example: "Découpeuse laser portable"
+	})
 	@MaxLength(128)
 	@MinLength(4)
 	machineName: string;
 
+	@ApiProperty({
+		example: "Découpe au laser"
+	})
 	@MaxLength(64)
 	@MinLength(2)
 	machineType: string;
 }
 
 export class TypeDto {
+	@ApiProperty({
+		description: "Un identifiant unique présent en base de donnée qui représente un MIME",
+		example: "dfd0fbb1-2bf3-4dbe-b86d-89b1bff5106c"
+	})
 	@IsUUID()
 	fileTypeId: string;
 }

apps/backend/src/main.ts

@@ -10,6 +10,11 @@ async function bootstrap() {
 		.setTitle("Fab Explorer")
 		.setDescription("Définition de l'api du FabLab Explorer")
 		.setVersion("1.0")
+		.addBearerAuth({
+			type: 'http',
+			scheme: 'bearer',
+			in: 'header',
+		})
 		.build();
 
 	const app = await NestFactory.create(AppModule);