Avez-vous déjà voulu avoir une documentation swagger pour votre API express basée sur des annotations? Je l'ai. Et malheureusement, nous n'avons trouvé aucun moyen de le faire sans avoir à créer manuellement un fichier swagger.json . Mon souhait était aussi simple que cela: je veux avoir une application express propre avec plusieurs points de terminaison et je veux garder la documentation swagger pour chaque point de terminaison proche de l'implémentation de point de terminaison, pas dans un fichier séparé.

Peut-être que je manque simplement de compétences Google, mais j'ai décidé qu'il serait beaucoup plus facile pour moi de créer un tel outil. Et le voici: mgr-swagger-express

Pour commencer

L'exemple ici sera écrit en TypeScript, mais la même chose peut être faite dans le projet Javascript.
Imaginez donc une application express classique:

Nous avons ici une ressource «Livre» et quelques points de terminaison CRUD de base. La question est «Comment ajouteriez-vous une documentation Swagger sympa à cette API?» Je voulais vraiment le faire en utilisant des annotations afin de garder chaque documentation de point final proche du point final lui-même.

Voici ce que vous pourrez faire avec mgr-swagger-express :
index.ts :

BookService.ts :

Il y a beaucoup plus de code, mais maintenant nous avons toute la documentation de swagger à côté du point de terminaison lui-même.
Voyons ce qui se passe ici:

• Dans le fichier d'index, nous créons notre application express, comme d'habitude. Nous devons également initialiser tous les middlewares (le bodyParser étant le plus important).
• Après cela, nous appelons SET_EXPRESS_APP pour définir l'objet d'application globalement. De cette façon, mgr-swagger-express pourra attacher des gestionnaires aux points de terminaison
• Ce n'est qu'après cela que nous pouvons importer le service avec des annotations. Il n'est pas nécessaire que ce soit une classe, il peut s'agir uniquement de fonctions.
• Ensuite, nous créons une instance de notre service (ou appelons une fonction init en cas de non utilisation des classes)
• Et nous générons la configuration swagger sur la base de toutes les annotations que nous avons dans le projet et l'attachons à notre application à l'aide du package swagger-ui-express

À l'intérieur du service, il se passe plusieurs choses, mais arrêtons-en quelques-unes seulement. Tout ce que vous pouvez facilement trouver dans le dépôt mgr-swagger-express:

• Dans le constructeur, nous appelons la fonction addSwaggerDefinition . Il enregistre un modèle swagger avec un nom donné. dans notre cas, nous définissons BookDefinition sous un nom de livre afin de le référencer ensuite par #/definitions/Book
• Tous les gestionnaires sont annotés avec les commandes @GET @POST @PUT @DELETE . Tous prennent en arguments un objet de type SwaggerEndpoint :
  

   path: string; auth?: string; description?: string; tags?: string[]; parameters?: SwaggerURLParameter[]; query?: SwaggerQueryParameter; body?: SwaggerBodyParameter; success?: SwaggerSuccessResponse; 

  
  

  Il s'agit essentiellement de l'objet de définition de point de terminaison classique, rien de spécial, sauf pour le champ auth, mais j'y reviendrai à l'avenir

  
  Tous les gestionnaires doivent avoir la signature suivante:
  

   (args: object, context: Context) => Promise<any> 

  
  

  L'objet args contient tous les paramètres acheminés vers votre point de terminaison. Il peut s'agir de paramètres URL (comme book_id dans notre exemple), de paramètres de requête ou même d'une valeur corporelle.

  
  
  

  L'objet de contexte est utilisé pour gérer l'authentification et la sécurité, mais encore une fois, à ce sujet plus tard.

  
  

  Conclusion

  
  

  Nous avons maintenant une API CRUD express simple annotée avec Swagger et une belle interface utilisateur Swagger, où toutes les définitions Swagger se trouvent à proximité de l'implémentation du point de terminaison. Comme d'habitude - toujours heureux d'avoir des commentaires! ️