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

http://localhost:3000/swagger

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.

Depuis la racine du projet :

cd apps/api

Installer les packages :

npm install @nestjs/swagger swagger-ui-express

Vérifier :

npm list @nestjs/swagger
 
npm list swagger-ui-express

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

Vérification :

npm list @nestjs/core

Exemple :

@nestjs/core@11.x

La version Swagger doit être cohérente :

@nestjs/swagger@11.x

Fichier :

apps/api/src/main.ts

Version minimale :

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();

npm run start:dev

Ouvrir :

http://localhost:3000/swagger

Vous devez voir :

Rental Platform API

Version 1.0.0

À ce stade :

0 endpoint

est normal.

Créer :

src/modules/health

import {
  Controller,
  Get,
} from '@nestjs/common';
 
@Controller('health')
export class HealthController {
 
  @Get()
  health() {
 
    return {
      status: 'UP',
    };
  }
}

import { Module } from '@nestjs/common';
 
import { HealthController }
from './health.controller';
 
@Module({
 
  controllers: [
    HealthController,
  ],
})
export class HealthModule {}

import { Module } from '@nestjs/common';
 
import { HealthModule }
from './modules/health/health.module';
 
@Module({
 
  imports: [
    HealthModule,
  ],
})
export class AppModule {}

Recharger :

http://localhost:3000/swagger

Vous devez voir :

GET /health

Déjà inclus dans :

@nestjs/swagger

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',
    };
  }
}

import { ApiProperty }
from '@nestjs/swagger';
 
export class HealthResponseDto {
 
  @ApiProperty({
    example: 'UP',
  })
  status: string;
}

@ApiOkResponse({
  type: HealthResponseDto,
})

Swagger affiche :

{
  "status": "UP"
}

avec son schéma JSON.

Dans :

nest-cli.json

Ajouter :

{
  "compilerOptions": {
    "plugins": [
      "@nestjs/swagger/plugin"
    ]
  }
}

npm install -D ts-patch

Puis :

npx ts-patch install

Swagger détectera automatiquement :

DTO

Types

Enums

Validators

sans configuration supplémentaire.

Installer :

npm install class-validator
 
npm install class-transformer

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;
}

Swagger documentera :

email

string

required

et

password

string

required

Dans main.ts :

import {
  ValidationPipe,
} from '@nestjs/common';
 
app.useGlobalPipes(
 
  new ValidationPipe({
 
    whitelist: true,
 
    forbidNonWhitelisted: true,
 
    transform: true,
  }),
);

Ajouter dans main.ts :

const config =
  new DocumentBuilder()
 
    .setTitle(
      'Rental Platform API'
    )
 
    .setVersion('1.0')
 
    .addBearerAuth(
      {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
      'JWT',
    )
 
    .build();

@ApiBearerAuth('JWT')

Bouton :

Authorize

dans Swagger.

Toujours dans main.ts :

import * as fs from 'fs';
 
fs.writeFileSync(
  './openapi.json',
  JSON.stringify(
    document,
    null,
    2,
  ),
);

Fichier :

apps/api/openapi.json

Ce fichier servira plus tard à :

SDK TypeScript

Client Frontend

Mock Server

Tests contractuels

Version finale recommandée :

SwaggerModule.setup(
  '/swagger',
  app,
  document,
  {
    swaggerOptions: {
 
      persistAuthorization: true,
 
      docExpansion: 'none',
 
      filter: true,
 
      displayRequestDuration: true,
    },
  },
);

Lorsque l'installation est terminée :

http://localhost:3000/swagger

doit afficher :

✓ Tags

✓ Endpoints

✓ DTO

✓ Schémas

✓ Validation

✓ JWT

✓ Réponses

✓ OpenAPI 3

✓ Export JSON

✓ Try It Out

✓ Authorize

✓ Temps d'exécution

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