Merge pull request #15 from DISIC/dev

fix(pencil): ajout de la documention des APIs avec Swagger

package.json

@@ -29,6 +29,7 @@
     "@nestjs/mongoose": "^10.0.2",
     "@nestjs/passport": "^10.0.3",
     "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/swagger": "^7.3.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^10.0.2",
     "@types/moment": "^2.13.0",

src/app.controller.ts

@@ -1,12 +1,7 @@
-import { Controller, Get } from '@nestjs/common';
+import { Controller } from '@nestjs/common';
 import { AppService } from './app.service';
 
 @Controller()
 export class AppController {
   constructor(private readonly appService: AppService) {}
-
-  @Get()
-  getHello(): string {
-    return this.appService.getHello();
-  }
 }

src/app.service.ts

@@ -1,8 +1,4 @@
 import { Injectable } from '@nestjs/common';
 
 @Injectable()
-export class AppService {
-  getHello(): string {
-    return '';
-  }
-}
+export class AppService {}

src/authentication/DTOs/LoginCallbackDTO.ts

@@ -1,10 +1,19 @@
 import { Injectable } from '@nestjs/common';
+import { ApiProperty } from '@nestjs/swagger';
 import { IsString } from 'class-validator';
 
 @Injectable()
 export class LoginCallbackDTO {
   @IsString()
+  @ApiProperty({
+    type: String,
+    description: "le code 'state' envoyé par le fournisseur d'identité",
+  })
   state: string;
   @IsString()
+  @ApiProperty({
+    type: String,
+    description: "le 'code' envoyé par le fournisseur d'identité",
+  })
   code: string;
 }

src/authentication/DTOs/LogoutCallbackDTO.ts

@@ -1,8 +1,13 @@
 import { Injectable } from '@nestjs/common';
+import { ApiProperty } from '@nestjs/swagger';
 import { IsString } from 'class-validator';
 
 @Injectable()
 export class LogoutCallbackDTO {
   @IsString()
+  @ApiProperty({
+    type: String,
+    description: "le code 'state' envoyé par le fournisseur d'identité",
+  })
   state: string;
 }

src/authentication/authentication.controller.ts

@@ -17,6 +17,12 @@ import { JwtService } from '@nestjs/jwt';
 import * as moment from 'moment';
 import { LoginCallbackDTO } from './DTOs/LoginCallbackDTO';
 import { LogoutCallbackDTO } from './DTOs/LogoutCallbackDTO';
+import {
+  ApiOkResponse,
+  ApiUnauthorizedResponse,
+  ApiNotFoundResponse,
+  ApiResponse,
+} from '@nestjs/swagger';
 
 @Controller('authentication')
 export class AuthenticationController {
@@ -28,12 +34,16 @@ export class AuthenticationController {
   ) {}
 
   @Get('whereami')
+  @ApiOkResponse({ description: "retoune 'RIE' ou 'INTERNET' " })
   whereami(@Headers('webconf-user-region') userAgent: string) {
     return userAgent;
   }
 
   @Get('login_authorize')
   @Redirect('', 302)
+  @ApiOkResponse({
+    description: "retourne l'url de redirection",
+  })
   loginAuthorize(
     @Res({ passthrough: true }) response: Response,
     @Query('room') room: string,
@@ -54,6 +64,16 @@ export class AuthenticationController {
   }
 
   @Get('login_callback')
+  @ApiOkResponse({
+    description: 'retourne un objet {roomName, jwt, accessToken}',
+  })
+  @ApiUnauthorizedResponse({
+    description: "le paramètre state recu n'est pas le meme envoyé",
+  })
+  @ApiNotFoundResponse({
+    description:
+      "erreur lors de récupération de l'accessToken ou userinfo d'agentConnect",
+  })
   async loginCallback(
     @Query() query: LoginCallbackDTO,
     @Req() request: Request,
@@ -97,6 +117,7 @@ export class AuthenticationController {
 
   @Get('logout')
   @Redirect('', 302)
+  @ApiResponse({ status: 302, description: 'redirection vers cerbère' })
   logout(
     @Req() request: Request,
     @Res({ passthrough: true }) response: Response,
@@ -114,7 +135,11 @@ export class AuthenticationController {
   }
 
   @Get('logout_callback')
-  // @Redirect('', 302)
+  @ApiOkResponse({ description: "retourne l'url /" })
+  @ApiUnauthorizedResponse({
+    description:
+      "le state de retour n'est pas la meme que celle qui a été envoyé",
+  })
   logoutCallback(
     @Query() query: LogoutCallbackDTO,
     @Req() request: Request,
@@ -135,6 +160,8 @@ export class AuthenticationController {
   }
 
   @Get('refreshToken')
+  @ApiOkResponse({ description: 'retourne { accessToken }' })
+  @ApiUnauthorizedResponse({ description: 'veuillez vous authentifier' })
   async refreshToken(
     @Req() request: Request,
     @Res({ passthrough: true }) response: Response,

src/authentication/authentication.service.ts

@@ -33,7 +33,7 @@ export class AuthenticationService {
         "la variable state envoyé n'est pas celle reçue {/authentication/login_callback} route",
       );
       throw new UnauthorizedException(
-        "le paramètre state recu n'est pas le meme envoyé",
+        "le paramètre state reçu n'est pas le meme envoyé",
       );
     }
 

src/conference/DTOs/byEmail.dto.ts

@@ -1,4 +1,5 @@
 import { Injectable } from '@nestjs/common';
+import { ApiProperty } from '@nestjs/swagger';
 import { IsEmail, Matches } from 'class-validator';
 
 @Injectable()
@@ -13,8 +14,10 @@ export class ByEmailDTO {
     ),
     { message: "le nom de conférence n'est pas valide" },
   )
+  @ApiProperty({ type: String })
   roomName: string;
 
   @IsEmail()
+  @ApiProperty({ type: String })
   email: string;
 }

src/conference/DTOs/conference.dto.ts

@@ -1,4 +1,5 @@
 import { Injectable } from '@nestjs/common';
+import { ApiProperty } from '@nestjs/swagger';
 import { Matches } from 'class-validator';
 
 @Injectable()
@@ -13,5 +14,6 @@ export class roomNameDTO {
     ),
     { message: "le nom de conférence n'est pas valide" },
   )
+  @ApiProperty({ type: String, description: 'nom de la conférence' })
   roomName: string;
 }