Documenter les API de NestJS avec Swagger

Swagger est une structure totalement gratuite et open-source pour développer des documents d’API interactifs et également simples. Elle génère des sites web interactifs qui vous permettent d’évaluer une API avec de nombreuses entrées.

Swagger prend en charge à la fois les hausses JSON et également XML. La documentation qu’il produit convient aux programmeurs et aux non-développeurs.

Vous pouvez documenter vos API internet NestJS via Swagger en utilisant des designers simples, sans avoir besoin de quitter votre IDE.

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

Avant de commencer, vous devez développer une API d’essai que Swagger va générer ses documents.

Vous allez certainement générer l’API de démonstration à partir de zéro en faisant usage de la CLI NestJS.

Tout d’abord, produisez une toute nouvelle tâche NestJS en exécutant :

Ensuite, transformez le répertoire de votre tâche déjà produite en exécutant :

Ensuite, vous allez produire une API REST avec le CLI en exécutant :

Vous verrez une demande demandant : « Quelle couche de transport utilisez-vous ? » pioche. API REST.

Vous verrez une autre question demandant : « Souhaitez-vous générer des points d’entrée CRUD ? ». Tapez Y ainsi que tapez Entrez .

La commande over génère une API REST complètement pratique avec des endpoints CRUD et sans les fichiers de tests unitaires. Pour cette raison, la commande — no-spec dans la commande over.

Étape 2 : Installer Swagger

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

Étape 3 : Configurer Swagger

Dans votre main. ts documents, importez SwaggerModule et DocumentBuilder de @nestjs/swagger .

DocumentBuilder aide à la structuration d’un document de base. Il fournit de nombreuses méthodes que l’on peut enchaîner les unes avec les autres ainsi que fermer avec l’option build méthode.

Voir aussi :  Comment lire et écrire des fichiers JSON dans Node.js

Ces techniques permettent d’agencer de nombreuses caractéristiques, telles que le titre, la description, ainsi que la variation.

Créez un config dans votre bootstrap fonctionne comme suit :

Une toute nouvelle circonstance de DocumentBuilder produit un fichier de base qui correspond au fichier de base de l’utilisateur. Spécification OpenAPI . Vous pouvez ensuite utiliser cette instance pour établir le titre, la description, ainsi que la version via leurs techniques appropriées.

Ensuite, vous devrez créer un document total avec toutes les routes HTTP spécifiées en utilisant l’enregistrement de base.

Pour ce faire, appelez l’instance createDocument sur SwaggerModule. createDocument accepte deux arguments : une circonstance d’application et un objet d’options Swagger. Stockez le résultat de cette employer une variable pour une utilisation ultérieure :

Ensuite, appelez la méthode setup sur SwaggerModule. L’approche de configuration absorbe trois désaccords :

  1. Le cours Swagger UI. Par convention, vous pouvez utiliser « api ».
  2. Une instance d’application
  3. Le fichier complet

En outre, l’approche d’arrangement prend un objet optionnel d’options. Voir Le document de NestJS sur les choix d’enregistrements Swagger. pour obtenir plus d’informations le concernant.

Comme ça :

Démarrez votre application et très probablement à http:// localhost:
< PORT>/ api

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

L’image ci-dessus est la vue par défaut de l’interface utilisateur Swagger, avec tous les chemins HTTP de votre contrôleur spécifiés. Vous devrez la personnaliser pour l’adapter à la capacité de votre API.

Voir aussi :  Introduction au routage dans Svelte

Étape 4 : personnalisation des propriétés de l’API

Par défaut, Swagger préfixe toute la zone de cours HTTP avec un titre qui révise « default ». Vous pouvez transformer cela en annotant votre classe de contrôleur avec la balise @ApiTags designer et en passant votre balise préférée comme argument.

Comme ça :

La section Schemas se compose des éléments de transfert de données de votre API. Actuellement, l’interface utilisateur se compose d’aucun de leurs propriétés résidentielles ou commerciales.

Pour déclarer leurs bâtiments dans l’interface utilisateur, il suffit d’ajouter des concepteurs. Annotez chaque bâtiment appelé avec la balise @ApiProperty designer. Annotez les propriétés résidentielles ou commerciales facultatives avec le concepteur @ApiProperty . @ApiPropertyOptional décorateur.

Par exemple :

Les décorateurs @ApiProperty et aussi @ApiPropertyOptional acceptent chacun un élément d’option. Cet élément définit la maison qui se conforme à ci-dessous.

Notez que l’objet alternatives utilise JavaScript, et non TypeScript. Pour cette raison, le genre JavaScript affirme (c’est-à-dire String, et non string).

L’annotation des foyers de l’objet Data-transfer ajoute une instance des données attendues à la zone Schemas. Elle met également à jour le parcours HTTP lié avec une instance des données attendues.

Étape 5 : définir les réponses de l’API

Dans votre classe de contrôleur, faites usage de la fonction @ApiResponse pour enregistrer toutes les réponses anticipées pour chaque route HTTP. Pour chaque endpoint, les différents décorateurs @ApiResponse définissent le type de réponses à anticiper.

Nous avons expliqué les actions HTTP habituelles, au cas où vous ne seriez pas familier avec ce qu’elles impliquent.

Les décorateurs @ApiResponse acceptent une chose facultative qui explique la réaction.

Voir aussi :  11 requêtes et opérations MongoDB à connaître absolument

Réponses POST courantes

Pour une demande POST, les actions les plus probables comprennent :

  • ApiCreatedResponse , pour les réactions créées 201 réussies.
  • ApiUnprocessableEnityResponse , pour les actions courtes tombées 422 d’entités non traitables.
  • ApiForbiddenResponse , pour les réactions 403 interdites.

Par exemple :

Réponses GET courantes

Pour les demandes GET, les réactions les plus probables comprennent :

  • ApiOkResponse , pour 200 réactions droites.
  • ApiForbiddenResponse , pour 403 réactions interdites.
  • ApiNotFoundResponse , pour les retours d’information 404 non trouvés.

Par exemple :

Réponses communes de PATCH et aussi de UPDATE.

Pour les demandes de PATCH et aussi de UPDATE, les actions probables comprennent :

  • ApiOkResponse , pour les réactions 200 ok.
  • ApiNotFoundResponse , pour les actions 404 not-found.
  • ApiUnprocessibleEntityResponse , pour l’échec de 422 réactions d’entités non traitables.
  • ApiForbiddenResponse , pour les réactions interdites 403.

Par exemple :

Réponses DELETE courantes

Pour les demandes DELETE, les actions probables comprennent :

  • ApiOkResponse , pour les actions 200 alright.
  • ApiForbiddenResponse , pour les actions interdites 403.
  • ApiNotFoundResponse , pour les réactions 404 non trouvées.

Par exemple :

Ces concepteurs occupent votre documentation avec des réactions possibles. Vous pouvez les visualiser en utilisant la liste déroulante à côté de chaque chemin.

Visualisation de votre documentation

Lorsque votre configuration est totale, vous pouvez voir votre documentation sur . localhost:< PORT>/ api . Il doit faire apparaître votre paperasse interactive de l’API.

Les éléments essentiels des documents API Swagger sont le résumé, les types de réaction, ainsi que la signification du schéma. Ce sont les choses standard requises pour développer une grande documentation d’API.

Cliquez pour évaluer cet article !
[Total: Moyenne : ]

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *