Swagger est un framework gratuit et open source pour créer une documentation d'API interactive et conviviale. Il génère des pages Web interactives qui vous permettent de tester une API avec différentes entrées.

Swagger prend en charge les charges utiles JSON et XML. La documentation qu'il génère convient aux développeurs et aux non-développeurs.

Vous pouvez documenter vos API Web NestJS via Swagger à l'aide de décorateurs simples, sans avoir à quitter votre IDE.

Étape 1: Générer l'API

Avant de commencer, vous devez créer une API de démonstration que Swagger générera sa documentation.

Vous allez générer l'API de démonstration à partir de zéro à l'aide de la CLI NestJS.

Tout d'abord, générez un nouveau projet NestJS en exécutant :

nid nouveau <nom-de-votre-projet>

Ensuite, changez le répertoire de votre projet déjà créé en exécutant :

CD <nom-de-votre-projet>

Ensuite, vous allez générer une API REST avec la CLI en exécutant :

Nest génère une démo de ressource --no-spec

Vous verrez une requête demandant: "Quelle couche de transport utilisez-vous ?" sélectionner API REST.

instagram viewer

Vous verrez une autre requête demandant: "Voulez-vous générer des points d'entrée CRUD ?" Taper Oui et frappe Entrer.

La commande ci-dessus génère une API REST entièrement fonctionnelle avec les points de terminaison CRUD et sans les fichiers de test unitaire. D'où le --no-spec drapeau dans la commande ci-dessus.

Étape 2: Installer Swagger

Installez Swagger et sa bibliothèque Express UI en exécutant :

npm installer--save @nestjs/swagger swagger-ui-express

Étape 3: Configurer Swagger

Dans ton main.ts fichier, importer Module Swagger et Générateur de documents de @nestjs/swagger.

DocumentBuilder aide à structurer un document de base. Il fournit plusieurs méthodes que vous pouvez enchaîner et fermer avec le construire méthode.

Ces méthodes permettent la configuration de nombreux attributs, tels que le titre, la description et la version.

Créer un configuration variable objet dans votre amorcer fonctionner comme ceci :

constante configuration = Nouveau Générateur de documents()
 .setTitle('API démo')
 .setDescription('Une API de démonstration avec Fonctionnalité CRUD')
 .setVersion('1.0')
 .construire();

Une nouvelle instance de DocumentBuilder crée un document de base qui correspond au Spécification OpenAPI. Vous pouvez ensuite utiliser cette instance pour définir le titre, la description et la version via leurs méthodes appropriées.

Ensuite, vous devrez créer un document complet avec toutes les routes HTTP définies à l'aide du document de base.

Pour ce faire, appelez le créerDocument méthode sur SwaggerModule. createDocument accepte deux arguments: une instance d'application et un objet d'options Swagger. Stockez le résultat de cet appel dans une variable pour une utilisation ultérieure :

constantedocument = SwaggerModule.createDocument (application, configuration);

Ensuite, appelez le mettre en place méthode sur SwaggerModule. La méthode setup prend trois arguments :

  1. Le chemin de l'interface utilisateur Swagger. Par convention, vous pouvez utiliser « api ».
  2. Une instance d'application
  3. Le dossier complet

De plus, la méthode de configuration prend un objet d'options facultatif. Voir Documentation de NestJS sur les options de document Swagger pour en savoir plus.

Ainsi:

SwaggerModule.setup('API', application, document) ;

Démarrez votre application et accédez à http://localhost:/api

Vous devriez voir l'interface utilisateur Swagger affichée sur la page.

L'image ci-dessus est la vue par défaut de l'interface utilisateur Swagger, avec toutes les routes HTTP définies dans votre contrôleur. Vous devrez le personnaliser pour l'adapter à la fonctionnalité de votre API.

Étape 4: Personnaliser les propriétés de l'API

Par défaut, Swagger préfixe l'intégralité de la section de route HTTP avec un en-tête indiquant « par défaut ». Vous pouvez changer cela en annotant votre classe de contrôleur avec le @ApiTags décorateur et en passant votre tag préféré comme argument.

Ainsi:

// demo.controller.ts
importer { Balises API } de '@nestjs/swagger';
@ApiTags("Démo")
@Manette('démo')
exporterclasser Contrôleur démo {

La section Schémas contient les objets de transfert de données dans votre API. Actuellement, l'interface utilisateur n'inclut aucune de leurs propriétés.

Pour déclarer leurs propriétés dans l'interface utilisateur, ajoutez simplement des décorateurs. Annotez chaque propriété requise avec le @ApiProperty décorateur. Annotez les propriétés facultatives avec le @ApiPropertyOptional décorateur.

Par exemple:

// créer-demo.dto.ts
importer { ApiProperty, ApiPropertyFacultatif } de '@nestjs/swagger';
exporterclasser CreateDemoDto {
@ApiProperty({
taper: Chaîne de caractères,
 description: 'Ceci est une propriété obligatoire',
 })
 propriété: chaîne de caractères;
@ApiPropertyOptional({
taper: Chaîne de caractères,
 description: 'Ceci est une propriété facultative',
 })
 propriétéoptionnelle: chaîne de caractères;
}

Les décorateurs @ApiProperty et @ApiPropertyOptional acceptent chacun un objet options. Cet objet décrit la propriété qui suit ci-dessous.

Notez que l'objet options utilise JavaScript, pas TypeScript. D'où les déclarations de type JavaScript (c'est-à-dire String, pas string).

L'annotation des propriétés de l'objet Data-transfer ajoute un exemple des données attendues à la section Schemas. Il met également à jour la route HTTP associée avec un exemple des données attendues.

Étape 5: Définir les réponses de l'API

Dans votre classe de contrôleur, utilisez le @ApiResponse décorateurs pour documenter toutes les réponses potentielles pour chaque route HTTP. Pour chaque point de terminaison, les différents décorateurs @ApiResponse décrivent le type de réponses à attendre.

Nous avons expliqué réponses HTTP courantes, au cas où vous ne seriez pas familier avec leur signification.

Les décorateurs @ApiResponse acceptent un objet facultatif qui décrit la réponse.

Réponses POST courantes

Pour une requête POST, les réponses probables incluent :

  • ApiCreatedResponse, pour les 201 réponses créées réussies.
  • ApiUnprocessableEnityResponse, pour les réponses d'entité non traitables 422 ayant échoué.
  • ApiForbiddenResponse, pour 403 réponses interdites.

Par exemple:

// demo.controller.ts
@Poste()
@ApiCreatedResponse({ description: 'Créé avec succès' })
@ApiUnprocessableEntityResponse({ description: 'Mauvaise demande' })
@ApiForbiddenResponse({ description: 'Demande non autorisée' })
 créer(@Corps() createDemoDto: CreateDemoDto) {
revenircette.demoService.create (createDemoDto);
 }

Réponses GET courantes

Pour les requêtes GET, les réponses probables incluent :

  • ApiOkResponse, pour 200 réponses ok.
  • ApiForbiddenResponse, pour 403 réponses interdites.
  • ApiNotFoundResponseApiNotFoundResponse, pour 404 réponses non trouvées.

Par exemple:

// demo.controller.ts
@Obtenir()
@ApiOkResponse({ description: 'Les ressources ont été renvoyées avec succès' })
@ApiForbiddenResponse({ description: 'Demande non autorisée' })
 Trouver tout() {
revenircette.demoService.findAll();
 }
@Obtenir(':identifiant')
@ApiOkResponse({ description: 'La ressource a été renvoyée avec succès' })
@ApiForbiddenResponse({ description: 'Demande non autorisée' })
@ApiNotFoundResponse({ description: 'Ressource introuvable' })
 trouverUn(@Param('J'ai fait: chaîne de caractères) {
revenircette.demoService.findOne(+id);
 }

Réponses PATCH et UPDATE courantes

Pour les requêtes PATCH et UPDATE, les réponses probables incluent :

  • ApiOkResponse, pour 200 réponses ok.
  • ApiNotFoundResponseApiNotFoundResponse, pour 404 réponses non trouvées.
  • ApiUnprocessibleEntityResponseApiUnprocessibleEntityResponse, pour les réponses d'entité non traitables 422 ayant échoué.
  • ApiForbiddenResponse, pour 403 réponses interdites.

Par exemple:

// demo.controller.ts
@Correctif(':identifiant')
@ApiOkResponse({ description: 'La ressource a été mise à jour avec succès' })
@ApiNotFoundResponse({ description: 'Ressource introuvable' })
@ApiForbiddenResponse({ description: 'Demande non autorisée' })
@ApiUnprocessableEntityResponse({ description: 'Mauvaise demande' })
 mettre à jour(@Param('J'ai fait: chaîne de caractères, @Corps() updateDemoDto: UpdateDemoDto) {
revenircette.demoService.update(+id, updateDemoDto);
 }

Réponses DELETE courantes

Pour les requêtes DELETE, les réponses probables incluent :

  • ApiOkResponse, pour 200 réponses ok.
  • ApiForbiddenResponse, pour 403 réponses interdites.
  • ApiNotFoundResponseApiNotFoundResponse, pour 404 réponses non trouvées.

Par exemple:

// demo.controller.ts
@Effacer(':identifiant')
@ApiOkResponse({ description: 'La ressource a été renvoyée avec succès' })
@ApiForbiddenResponse({ description: 'Demande non autorisée' })
@ApiNotFoundResponse({ description: 'Ressource introuvable' })
 retirer(@Param('J'ai fait: chaîne de caractères) {
revenircette.demoService.remove(+id);
 }

Ces décorateurs remplissent votre documentation avec des réponses possibles. Vous pouvez les afficher à l'aide du menu déroulant à côté de chaque itinéraire.

Affichage de votre documentation

Lorsque votre configuration est terminée, vous pouvez consulter votre documentation sur hôte local :/api. Cela devrait faire apparaître la documentation de votre API interactive.

Les éléments essentiels de la documentation de l'API Swagger sont la description, les types de réponse et la définition du schéma. Ce sont les éléments de base nécessaires pour créer une bonne documentation d'API.