====== Détail complet de l'installation Swagger dans NestJS ======

===== Objectif =====

À la fin de cette étape, les développeurs doivent pouvoir accéder à :

<code>
http://localhost:3000/swagger
</code>

et visualiser automatiquement :

  * Les endpoints REST
  * Les DTO
  * Les schémas JSON
  * Les réponses HTTP
  * Les erreurs
  * L'authentification JWT

Swagger deviendra la documentation vivante de l'API.

----

====== Étape 1 — Installer les dépendances ======

Depuis la racine du projet :

<code bash>
cd apps/api
</code>

Installer les packages :

<code bash>
npm install @nestjs/swagger swagger-ui-express
</code>

Vérifier :

<code bash>
npm list @nestjs/swagger

npm list swagger-ui-express
</code>

----

====== Étape 2 — Vérifier la version NestJS ======

Swagger doit être compatible avec la version de NestJS utilisée.

Vérification :

<code bash>
npm list @nestjs/core
</code>

Exemple :

<code>
@nestjs/core@11.x
</code>

La version Swagger doit être cohérente :

<code>
@nestjs/swagger@11.x
</code>

----

====== Étape 3 — Modifier main.ts ======

Fichier :

<code>
apps/api/src/main.ts
</code>

Version minimale :

<code typescript>
import { NestFactory } from '@nestjs/core';

import { AppModule } from './app.module';

import {
  SwaggerModule,
  DocumentBuilder,
} from '@nestjs/swagger';

async function bootstrap() {

  const app =
    await NestFactory.create(AppModule);

  const config =
    new DocumentBuilder()

      .setTitle('Rental Platform API')

      .setDescription(
        'Documentation API'
      )

      .setVersion('1.0.0')

      .build();

  const document =
    SwaggerModule.createDocument(
      app,
      config,
    );

  SwaggerModule.setup(
    'swagger',
    app,
    document,
  );

  await app.listen(3000);
}

bootstrap();
</code>

----

====== Étape 4 — Lancer l'API ======

<code bash>
npm run start:dev
</code>

----

====== Étape 5 — Vérifier Swagger ======

Ouvrir :

<code>
http://localhost:3000/swagger
</code>

Vous devez voir :

<code>
Rental Platform API

Version 1.0.0
</code>

À ce stade :

<code>
0 endpoint
</code>

est normal.

----

====== Étape 6 — Créer un premier contrôleur ======

Créer :

<code>
src/modules/health
</code>

----

===== health.controller.ts =====

<code typescript>
import {
  Controller,
  Get,
} from '@nestjs/common';

@Controller('health')
export class HealthController {

  @Get()
  health() {

    return {
      status: 'UP',
    };
  }
}
</code>

----

===== health.module.ts =====

<code typescript>
import { Module } from '@nestjs/common';

import { HealthController }
from './health.controller';

@Module({

  controllers: [
    HealthController,
  ],
})
export class HealthModule {}
</code>

----

===== app.module.ts =====

<code typescript>
import { Module } from '@nestjs/common';

import { HealthModule }
from './modules/health/health.module';

@Module({

  imports: [
    HealthModule,
  ],
})
export class AppModule {}
</code>

----

====== Étape 7 — Vérifier l'apparition dans Swagger ======

Recharger :

<code>
http://localhost:3000/swagger
</code>

Vous devez voir :

<code>
GET /health
</code>

----

====== Étape 8 — Documenter les endpoints ======

===== Installer les décorateurs =====

Déjà inclus dans :

<code>
@nestjs/swagger
</code>

----

===== Exemple =====

<code typescript>
import {
  ApiTags,
  ApiOperation,
  ApiResponse,
} from '@nestjs/swagger';

@ApiTags('Health')

@Controller('health')

export class HealthController {

  @Get()

  @ApiOperation({
    summary:
      'Health Check',
  })

  @ApiResponse({
    status: 200,
    description:
      'Application available',
  })

  health() {

    return {
      status: 'UP',
    };
  }
}
</code>

----

====== Étape 9 — Ajouter des DTO ======

===== health-response.dto.ts =====

<code typescript>
import { ApiProperty }
from '@nestjs/swagger';

export class HealthResponseDto {

  @ApiProperty({
    example: 'UP',
  })
  status: string;
}
</code>

----

===== Utilisation =====

<code typescript>
@ApiOkResponse({
  type: HealthResponseDto,
})
</code>

----

===== Résultat Swagger =====

Swagger affiche :

<code json>
{
  "status": "UP"
}
</code>

avec son schéma JSON.

----

====== Étape 10 — Activer les DTO automatiquement ======

Dans :

<code>
nest-cli.json
</code>

Ajouter :

<code json>
{
  "compilerOptions": {
    "plugins": [
      "@nestjs/swagger/plugin"
    ]
  }
}
</code>

----

===== Installation complémentaire =====

<code bash>
npm install -D ts-patch
</code>

Puis :

<code bash>
npx ts-patch install
</code>

----

===== Avantage =====

Swagger détectera automatiquement :

<code>
DTO

Types

Enums

Validators
</code>

sans configuration supplémentaire.

----

====== Étape 11 — Intégrer la validation ======

Installer :

<code bash>
npm install class-validator

npm install class-transformer
</code>

----

===== Exemple DTO =====

<code typescript>
import {
  IsEmail,
  IsString,
} from 'class-validator';

import {
  ApiProperty,
} from '@nestjs/swagger';

export class RegisterDto {

  @ApiProperty({
    example:
      'john@acme.com',
  })
  @IsEmail()
  email: string;

  @ApiProperty({
    example:
      'Password123!',
  })
  @IsString()
  password: string;
}
</code>

----

===== Résultat Swagger =====

Swagger documentera :

<code>
email

string

required
</code>

et

<code>
password

string

required
</code>

----

====== Étape 12 — Activer ValidationPipe ======

Dans main.ts :

<code typescript>
import {
  ValidationPipe,
} from '@nestjs/common';

app.useGlobalPipes(

  new ValidationPipe({

    whitelist: true,

    forbidNonWhitelisted: true,

    transform: true,
  }),
);
</code>

----

====== Étape 13 — Configurer JWT dans Swagger ======

Ajouter dans main.ts :

<code typescript>
const config =
  new DocumentBuilder()

    .setTitle(
      'Rental Platform API'
    )

    .setVersion('1.0')

    .addBearerAuth(
      {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
      'JWT',
    )

    .build();
</code>

----

===== Sur les endpoints =====

<code typescript>
@ApiBearerAuth('JWT')
</code>

----

===== Résultat =====

Bouton :

<code>
Authorize
</code>

dans Swagger.

----

====== Étape 14 — Générer le JSON OpenAPI ======

Toujours dans main.ts :

<code typescript>
import * as fs from 'fs';

fs.writeFileSync(
  './openapi.json',
  JSON.stringify(
    document,
    null,
    2,
  ),
);
</code>

----

===== Résultat =====

Fichier :

<code>
apps/api/openapi.json
</code>

Ce fichier servira plus tard à :

<code>
SDK TypeScript

Client Frontend

Mock Server

Tests contractuels
</code>

----

====== Étape 15 — Configuration Enterprise recommandée ======

Version finale recommandée :

<code typescript>
SwaggerModule.setup(
  '/swagger',
  app,
  document,
  {
    swaggerOptions: {

      persistAuthorization: true,

      docExpansion: 'none',

      filter: true,

      displayRequestDuration: true,
    },
  },
);
</code>

----

====== Vérification finale ======

Lorsque l'installation est terminée :

<code>
http://localhost:3000/swagger
</code>

doit afficher :

✓ Tags

✓ Endpoints

✓ DTO

✓ Schémas

✓ Validation

✓ JWT

✓ Réponses

✓ OpenAPI 3

✓ Export JSON

✓ Try It Out

✓ Authorize

✓ Temps d'exécution

----

====== Livrable obtenu ======

Vous disposez désormais d'un Swagger Enterprise prêt à documenter les ~500 endpoints prévus par les 20 sprints de la plateforme.