Devriez-vous combiner Swagger avec HATEOAS / HAL / JSON-LD?
J'utilise Swagger pour mon API ASP.NET Core en utilisant Swashbuckle qui décrit mon API dans un document séparé et fournit une interface utilisateur agréable pour toutes ces informations.
Y a-t-il des avantages à utiliser quelque chose comme HATEOAS, HAL ou JSON-LD qui modifient le document lui-même en combinaison avec Swagger?
Ici est un exemple de quelqu'un utilisant Swagger avec HAL.
Comme Sampada l'a déclaré, Swagger et HATEOAS ajoutent plus de valeur aux différentes dimensions de votre API.
Swagger ajoutera de la valeur au cycle de vie du développement, rendant votre API plus compréhensible et navigable au moment du développement.
[~ # ~] hateoas [~ # ~] ajoutera de la valeur à votre API lorsqu'elle est utilisée par les clients. Les liens fournis par HATEOAS vous donnent la possibilité de lier différentes parties (c'est-à-dire: les ressources) de votre API sans avoir à coder en dur ces liens dans le code client de vos applications.
En supposant que vous ayez un contrat avec quelques documents s'y rapportant. Une façon assez courante de modéliser cela serait d'utiliser deux ressources:
- Ressource de contrat - vous a donné des opérations pour répertorier, ajouter, supprimer, modifier des contrats;
- Documents Resource - vous a donné des opérations pour lister, ajouter, supprimer, modifier des documents
Pour lier ces deux ensembles, vous pouvez ajouter des champs dans les deux modèles de ressources contenant des tableaux de la ressource associée. De plus, vous devez également implémenter ces connaissances implicites dans votre application client. De cette façon, vous ajouterez (vous ajouterez) de l'encombrement à vos représentations de ressources au fil du temps, en le polluant avec des informations sur les relations avec d'autres objets.
C'est là que HATEOAS entre en jeu, à la fois en déplaçant ces informations de propriété hors de vos objets métier et en fournissant un moyen unifié de gérer ces relations. Les deux objets métier des ressources incluraient désormais un en-tête ou un champ de valeur standardisé contenant les informations sur toutes les relations du courant Ressource. Par exemple. Une ressource de contrat aurait désormais 3 liens avec l'attribut rel "document" reliant aux ressources documentaires appropriées et 1 lien avec l'attribut rel "order" reliant à la commande dont ce contrat est issu.
Autant que je sache JSON-LD est utilisé pour normaliser le vocabulaire des différentes API, ce qui le rend plus facile à utiliser les côte à côte. Certains pourraient utiliser firstName & lastName comme propriété d'objets Person, tandis que d'autres auraient appelé les propriétés givenName & familyName. Avec JSON-LD, vous pouvez mapper les deux objets à un nom commun. Vous pourriez envisager de jeter un œil à ce lien: DZone - Json-LD
Il y a des avantages certains à intégrer HATEOAS dans votre code API en plus d'utiliser Swagger.
Swagger ajoute de la forme à vos API en les rendant belles et présentables afin que le code client puisse être écrit facilement, en même temps, il fait aussi de la documentation une tâche beaucoup moins ennuyeuse en l'intégrant au code. Inutile de dire que cela permet également d'économiser le temps supplémentaire nécessaire pour documenter une fois le codage terminé. En ce sens, c'est un peu révolutionnaire.
HATEOAS d'autre part rend vos API auto-détectables en activant Level 3 RMM . Cela facilite la navigation d'une API à l'autre. L'idée est d'avoir une URL de base qu'un client peut utiliser et le reste des API REST sont découverts à partir de cette URL de base.
Maintenant, la question est, pourquoi avoir les deux? Eh bien, cela ajoute simplement plus de dimension à vos API Restful et donne aux clients plus de choix pour très peu d'effort de codage. Qui ne voudrait pas ça?
Pensez à vous pencher sur Hydra:
Hydra est un vocabulaire pour JSON-LD qui vous permet d'incorporer des contrôles hypermédia dans vos données. De plus, vous pouvez fournir un point de terminaison de documentation API jouant un rôle similaire à la définition Swagger. Ce que j'aime chez Hydra, c'est que les contrôles hypermédia sont intégrés dans les réponses plutôt que hors bande dans une définition de service en quelque sorte. JSON-LD et Schema.org valent vraiment la peine d'être examinés étant donné la façon dont Google et Microsoft les soutiennent dans leurs produits.
Hydra est encore relativement nouveau, donc les outils disponibles ne sont pas aussi solides que pour Swagger.