Commencer avec swagger

Introduction - Installation - Configuration (Développement en 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 d’outils puissant et activement développé autour de cette spécification formelle, comme des générateurs de code et des é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 qu’est l’arrogance : la mise en route.

Spécifications rédactionnelles :

Les spécifications peuvent être écrites en JSON ou en YAML. Et donc nous créons 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 : **

    • Approche API d’abord (approche descendante): * Utilisez l’éditeur swagger → Écrivez les définitions swagger → Utilisez swagger-codegen et swagger-ui pour générer des API
  2. Approche de service d’abord (approche ascendante) : Développer des classes de ressources JAX-RS à l’aide d’annotations swagger → Utiliser swagger-core pour générer automatiquement les définitions swagger → Utiliser swagger-codegen et swagger-ui pour générer des API client et des documentations. Ce qui précède peut être fait pendant la construction de maven pendant le plugin 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 client en l’utilisant. Pour installer swagger à l’aide du gestionnaire de packages Node, exécutez la commande suivante :

npm install -g swagger

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

projet swagger créer <nom-projet>

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

-API/ - controllers/ - helpers/ - mocks/ - swagger/

  • configuration/
  • test/
    • api/
      • controllers/
      • helpers
  • app.js
  • package.json

Le serveur est pratiquement prêt maintenant et peut être démarré à l’aide de cette commande à exécuter à la racine du projet :

début de projet swagger

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

modifier le projet swagger

Cela ouvrira l’éditeur swagger dans un onglet du navigateur sur un port généré de manière aléatoire. Un exemple de requête hello GET est déjà présent dans le fichier swagger.yaml. Toute autre modification de ce fichier entraînera le redémarrage du serveur de lui-même.

Dans la section des chemins, la valeur utilisée pour x-swagger-router-controller doit être le nom du fichier javascript dans le dossier des contrôleurs. À titre d’exemple, hello_world.js devrait être présent dans le répertoire des contrôleurs. De plus, 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 swagger est terminée et peut être utilisée pour développer davantage notre API.

renard printanier →