swagger Tutoriel
Commencer avec Swagger

Remarques

Introduction - Installation - Configuration (Développement dans Node.js)

Introduction:

Swagger est un ensemble de règles / spécifications pour un format décrivant les API REST. Il fournit un écosystème puissant et activement développé autour de cette spécification formelle, comme les générateurs de code et les éditeurs. La meilleure partie de Swagger est que la documentation des méthodes, des paramètres et des modèles est étroitement intégrée au code du serveur, permettant aux API de toujours rester synchronisées. Voici un lien donnant un bref aperçu de ce qui est swagger: démarrer.

Cahier des charges:

Les spécifications peuvent être écrites en JSON ou YAML. Nous avons donc créé le fichier swagger.json ou swagger.yaml en conséquence. L'éditeur en ligne peut être utilisé pour créer le fichier. Voici un lien décrivant la syntaxe des spécifications: http://swagger.io/specification/

Façons d'utiliser Swagger:

1. Première approche API (approche descendante): utilisez l'éditeur Swagger → Ecrire des définitions de swagger → Utilisez swagger-codegen et swagger-ui pour générer des API
2. Première approche du service (approche ascendante): Développer des classes de ressources JAX-RS à l'aide d'annotations de swagger → Utiliser swagger-core pour générer automatiquement les définitions de swagger → Utiliser swagger-codegen et swagger-ui pour générer des API et des documentations client. Ce qui précède peut être fait pendant la construction de Maven pendant le plug-in Swagger Maven.

Installation et configuration

Dans cette section, nous allons installer Swagger, configurer l'interface utilisateur Swagger et générer le SDK côté serveur et le client en l'utilisant. Pour installer swagger à l'aide du gestionnaire de paquets Node, exécutez la commande suivante:

npm install -g swagger

L'utilisation de l'option '-g' assurera que le module est installé globalement. Ensuite, nous allons créer un projet en utilisant la commande suivante:

swagger project create <project-name>

Cela demandera à l'utilisateur de sélectionner un cadre pour développer les API REST. Express peut être sélectionné pour le même. Cela créera le répertoire du projet avec les éléments suivants et un fichier README.md dans chacun d'eux:

• api /
  • contrôleurs /
  • helpers /
  • mocks /
  • swagger /
• config /
• tester/
  • api /
    • contrôleurs /
    • des aides
• app.js
• package.json

Le serveur est essentiellement prêt maintenant et peut être lancé en utilisant cette commande pour être exécuté dans la racine du projet:

swagger project start

Si le serveur hôte est défini en tant que localhost et que le numéro de port n'est pas modifié dans le fichier app.js , le serveur est démarré à l' http://localhost:10010 interface utilisateur de swagger peut être utilisée pour développer davantage nos API REST. Cela peut être démarré dans un nouveau terminal en utilisant:

swagger project edit

Cela ouvrira l'éditeur Swagger dans un onglet de navigateur sur un port généré de manière aléatoire. Un exemple de requête GET peut être vu déjà présent dans le fichier swagger.yaml. Toute modification ultérieure de ce fichier entraînera le redémarrage du serveur.

Dans la section des chemins, la valeur utilisée pour x-swagger-router-controller doit être le nom du fichier javascript dans le dossier controllers. Comme exemple, hello_world.js devrait être présent dans le répertoire controller. En outre, la valeur du paramètre operationId représente le nom de la fonction dans le fichier javascript ci-dessus. C'est là que la logique métier doit être écrite. Ainsi, notre configuration de swagger est complète et peut être utilisée pour développer notre API.