Introduction

La spécification OpenAPI est un format de définition indépendant du langage utilisé pour décrire des APIs RESTful. Nest fournit un module dédié qui permet de générer cette spécification en utilisant des décorateurs.

Installation

Pour commencer à l’utiliser, nous devons d’abord installer la dépendance requise.

$ npm install --save @nestjs/swagger

Bootstrap

Une fois le processus d’installation terminé, ouvrez le fichier main.ts et initialisez Swagger en utilisant la classe SwaggerModule :

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

Le DocumentBuilder aide à structurer un document de base qui respecte la spécification OpenAPI. Il fournit plusieurs méthodes permettant de définir des propriétés telles que le titre, la description, la version, etc. Pour créer un document complet (avec toutes les routes HTTP définies), nous utilisons la méthode createDocument() de la classe SwaggerModule. Cette méthode prend deux arguments : une instance d’application et un objet d’options Swagger. En option, nous pouvons fournir un troisième argument, qui devrait être de type SwaggerDocumentOptions. Plus d’informations dans la section des options de document.

Une fois le document créé, nous pouvons appeler la méthode setup(). Elle accepte :

Le chemin pour monter l’interface utilisateur de Swagger
Une instance d’application
L’objet document instancié ci-dessus
Un paramètre de configuration optionnel (lisez-en plus ici)

Maintenant, vous pouvez exécuter la commande suivante pour démarrer le serveur HTTP :

$ npm run start

Pendant que l’application fonctionne, ouvrez votre navigateur et accédez à http://localhost:3000/api. Vous devriez voir l’interface utilisateur de Swagger.

Swagger UI

Comme vous pouvez le voir, le SwaggerModule reflète automatiquement tous vos points d’entrée.

Pour générer et télécharger un fichier JSON Swagger, accédez à http://localhost:3000/api-json (en supposant que votre documentation Swagger est disponible à http://localhost:3000/api). Il est également possible de l’exposer sur un chemin de votre choix en utilisant uniquement la méthode setup de @nestjs/swagger, comme ceci :

SwaggerModule.setup('swagger', app, document, {
  jsonDocumentUrl: 'swagger/json',
});

Ce qui l’exposerait à http://localhost:3000/swagger/json

Lorsque vous utilisez fastify et helmet, il peut y avoir un problème avec CSP, pour résoudre ce conflit, configurez le CSP comme indiqué ci-dessous :

app.register(helmet, {
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", "data:", "validator.swagger.io"],
      scriptSrc: ["'self'", "https: 'unsafe-inline'"],
    },
  },
});

// Si vous ne comptez pas utiliser CSP du tout, vous pouvez utiliser ceci :
app.register(helmet, {
  contentSecurityPolicy: false,
});

Options de document

Lors de la création d’un document, il est possible de fournir quelques options supplémentaires pour affiner le comportement de la bibliothèque. Ces options doivent être de type SwaggerDocumentOptions, qui peuvent être les suivantes :

export interface SwaggerDocumentOptions {
  /**
   * Liste des modules à inclure dans la spécification
   */
  include?: Function[];

  /**
   * Modèles supplémentaires qui devraient être inspectés et inclus dans la spécification
   */
  extraModels?: Function[];

  /**
   * Si `true`, Swagger ignorera le préfixe global défini via la méthode `setGlobalPrefix()`
   */
  ignoreGlobalPrefix?: boolean;

  /**
   * Si `true`, Swagger chargera également les routes des modules importés par les modules `include`
   */
  deepScanRoutes?: boolean;

  /**
   * Custom operationIdFactory qui sera utilisé pour générer l'opération `operationId`
   * basé sur `controllerKey` et `methodKey`
   * @default () => controllerKey_methodKey
   */
  operationIdFactory?: (controllerKey: string, methodKey: string) => string;
}

Par exemple, si vous souhaitez vous assurer que la bibliothèque génère des noms d’opération comme createUser au lieu de UserController_createUser, vous pouvez définir ce qui suit :

const options: SwaggerDocumentOptions = {
  operationIdFactory: (controllerKey: string, methodKey: string) => methodKey,
};
const document = SwaggerModule.createDocument(app, config, options);

Options de configuration

Vous pouvez configurer l’interface utilisateur de Swagger en passant l’objet d’options qui respecte l’interface SwaggerCustomOptions comme quatrième argument de la méthode SwaggerModule#setup.

export interface SwaggerCustomOptions {
  /**
   * Si `true`, les chemins des ressources Swagger seront préfixés par le préfixe global défini via `setGlobalPrefix()`.
   * Par défaut : `false`.
   * @see https://docs.nestjs.com/faq/global-prefix
   */
  useGlobalPrefix?: boolean;

  /**
   * Si `false`, seules les définitions API (JSON et YAML) seront servies (sur `/{path}-json` et `/{path}-yaml`).
   * Cela est particulièrement utile si vous hébergez déjà une interface utilisateur Swagger ailleurs et que vous souhaitez simplement servir des définitions API.
   * Par défaut : `true`.
   */
  swaggerUiEnabled?: boolean;

  /**
   * URL pointant la définition API à charger dans l'interface utilisateur de Swagger.
   */
  swaggerUrl?: string;

  /**
   * Chemin de la définition API JSON à servir.
   * Par défaut : `<path>-json`.
   */
  jsonDocumentUrl?: string;

  /**
   * Chemin de la définition API YAML à servir.
   * Par défaut : `<path>-yaml`.
   */
  yamlDocumentUrl?: string;

  /**
   * Hook permettant de modifier le document OpenAPI avant qu'il ne soit servi.
   * Il est appelé après la génération du document et avant qu'il ne soit servi sous forme de JSON et YAML.
   */
  patchDocumentOnRequest?: <TRequest = any, TResponse = any>(
    req: TRequest,
    res: TResponse,
    document: OpenAPIObject
  ) => OpenAPIObject;

  /**
   * Si `true`, le sélecteur des définitions OpenAPI est affiché dans l'interface utilisateur Swagger.
   * Par défaut : `false`.
   */
  explorer?: boolean;

  /**
   * Options supplémentaires pour Swagger UI
   */
  swaggerOptions?: SwaggerUiOptions;

  /**
   * Styles CSS personnalisés à injecter dans la page de l'interface utilisateur de Swagger.
   */
  customCss?: string;

  /**
   * URL(s) d'une feuille de style CSS personnalisée à charger dans la page de l'interface utilisateur de Swagger.
   */
  customCssUrl?: string | string[];

  /**
   * URL(s) de fichiers JavaScript personnalisés à charger dans la page de l'interface utilisateur de Swagger.
   */
  customJs?: string | string[];

  /**
   * Scripts JavaScript personnalisés à charger dans la page de l'interface utilisateur de Swagger.
   */
  customJsStr?: string | string[];

  /**
   * Favicon personnalisé pour la page de l'interface utilisateur de Swagger.
   */
  customfavIcon?: string;

  /**
   * Titre personnalisé pour la page de l'interface utilisateur de Swagger.
   */
  customSiteTitle?: string;

  /**
   * Chemin du système de fichiers (ex : ./node_modules/swagger-ui-dist) contenant les actifs statiques de Swagger UI.
   */
  customSwaggerUiPath?: string;

  /**
   * @deprecated Cette propriété est sans effet.
   */
  validatorUrl?: string;

  /**
   * @deprecated Cette propriété est sans effet.
   */
  url?: string;

  /**
   * @deprecated Cette propriété est sans effet.
   */
  urls?: Record<'url' | 'name', string>[];
}

Exemple

Un exemple fonctionnel est disponible ici.