Quel est l'avantage d'utiliser Spring REST Documents comparant à Swagger
Spring REST Docs a été publié récemment et la documentation indique:
Cette approche vous libère des limitations imposées par des outils tels que Swagger.
Je voulais donc demander quand il est préférable d'utiliser Spring REST Docs pour comparer à Swagger et quelles sont les limitations qu'il libère.
Je viens de voir une présentation ici qui aborde votre question parmi d'autres sujets:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger ne supporte pas du tout l'hypermédia/il est centré sur l'URI
La méthode d'inspection de votre code par Swagger peut être en retard sur votre code. Il est possible de modifier votre code que Swagger ne comprend pas et ne sera pas traité correctement tant que Swagger n'aura pas été mis à jour.
Swagger nécessite beaucoup d'annotations et il est difficile d'inclure le texte descriptif souhaité dans un document api dans les annotations.
Swagger ne parvient pas à comprendre certaines choses en inspectant votre code.
En tout cas, ce ne sont que quelques points. Le présentateur discute beaucoup mieux que moi de la discussion.
Je pensais entrer dans les détails pour donner un peu plus de contexte concernant Swagger, ce que c'est et ce que ce n'est pas. Je pense que cela pourrait aider à répondre à votre question.
Swagger 2.0 est adopté par un grand nombre de grands noms et de grandes plates-formes telles que Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com, etc. Il ne faut pas oublier que Swagger est très simplement une spécification . Ce n'est pas un cadre. Il existe de nombreux frameworks conçus pour générer une sortie Swagger qui explore votre code en consultant les informations de votre API afin de créer le fichier JSON Swagger 2.0 qui représente votre API. L'interface utilisateur Swagger sur laquelle vous voyez vos API est directement gérée à partir de ce fichier JSON Swagger 2.0. fiddler pour le vérifier
Il est important de noter qu’un cadre créé pour vous permettre d’utiliser «swagger» n’est pas le mode de fonctionnement de Swagger (c’est-à-dire qu’il dépend totalement de la mise en œuvre du cadre tiers). Si le cadre que vous utilisez pour générer vos documents Swagger 2.0 et que l'interface utilisateur ne fonctionne pas pour vous, vous devriez pouvoir trouver un autre cadre qui génère les artefacts Swagger et permute les technologies.
J'espère que cela t'aides.
Il y a quelques limitations avec swagger et la pile de ressorts spécifique.
Par exemple: avec "param" dans votre mappage de demandes, vous pouvez définir plusieurs méthodes avec la même adresse URL, simplifiez donc votre code .
Depuis Spring REST docs :
Spring REST Docs a pour objectif de vous aider à produire une documentation précise et lisible pour vos services RESTful.
Cette approche axée sur les tests permet de garantir l’exactitude de la documentation de votre service. Si un extrait de code est incorrect, le test qui le génère échouera.
Les avantages de la documentation Spring REST:
- La documentation est écrite dans le code de test pour ne pas surcharger le code principal avec de nombreuses annotations et descriptions
- Les documents et exemples générés sont exacts car le test associé doit réussir
- Les documents peuvent fournir des extraits plus spécifiques et descriptifs
- Le format convient à la publication
Spring REST docs inconvénients:
- Nécessite plus de travail
- La documentation fournit des exemples de requête/réponse mais ne fournit pas d'outils interactifs pour modifier et tester les requêtes.
Avantages Swagger:
- Génération rapide et automatisée à partir d'un code
- Exécution interactive des demandes - peut être utilisé pour les tests d'acceptation
- Construit autour de OpenAPI Specification
Swagger inconvénients:
- Pour une documentation plus descriptive, il faudra beaucoup d'annotations
- Les tests n'étant pas liés à la documentation, la documentation peut parfois s'écarter de la réalité