Swagger est un outil spécial qui compose automatiquement le RESTful API document de votre application.
Son avantage réside dans le fait qu'il vous permet non seulement de consulter tous les points de terminaison de l'application, mais aussi de les tester immédiatement en action en envoyant une requête et en recevant une réponse.
Pour accéder à Swaggervous devez appuyer sur le bouton Preview dans l'application publiée et cliquer sur le nom du plan de publication souhaité (Deploy Plan).
Dans la fenêtre nouvellement ouverte, une liste des points de terminaison disponibles et des méthodes associées à ces points de terminaison est affichée. Certaines demandes ne sont disponibles que pour certains groupes d'utilisateurs autorisés (voir l'onglet Middleware de la Auth module pour chaque demande spécifique dans la Endpoints section ). A Bearer Token est nécessaire pour les demandes qui ne sont permises qu'aux utilisateurs autorisés.
Vous pouvez accéder directement au point de terminaison correspondant dans Swagger pour obtenir ce jeton (Auth section, POST /auth demande).
Appuyez sur Try it out et entrez le login et le mot de passe pour obtenir un jeton.
La demande sera envoyée sur Execute. Si elle a été envoyée avec succès, vous verrez un champ token avec la valeur Bearer token valeur.
La deuxième façon d'obtenir un jeton d'utilisateur autorisé est que le jeton peut être trouvé dans le corps de la requête de l'application déployée.
- Appuyez sur F12 dans votre navigateur web pour ouvrir l'outil du développeur.
- Envoyez n'importe quelle requête dans votre application déployée (pour mettre à jour des tables, par exemple). L'utilisateur qui envoie cette requête doit être autorisé à accéder à ce point de terminaison.
- Ouvrez l'onglet Network et trouvez la requête correspondante.
- Allez sur Headers onglet et trouvez Request Headers section. Bearer token sera présentée sous Authorization.
Fournissez Bearer token à Swagger en appuyant sur Authorize et en collant la valeur que vous avez copiée à l'étape précédente.
Pour les demandes de test, sélectionnez le groupe souhaité et la méthode que vous voulez exécuter. Appuyez sur Try it out et remplissez les paramètres d'entrée de la demande. Cliquez sur Execute pour exécuter la réponse.
La réponse la plus attendue, si la demande est correctement traitée par le serveur, a le code 200 et montre à quoi devrait ressembler la structure de la réponse.
401 - la demande n'a pas été traitée avec succès car le jeton d'autorisation requis est manquant ou non valide.
404 - la demande a été traitée avec succès, mais la ressource demandée n'a pas été trouvée.
422 - des paramètres incorrects ont été transmis à l'entrée de la demande.
500 - une erreur de traitement de la demande par le serveur.
Soulever une erreur personnalisée
Pour les BP personnalisés et les demandes associées, il est possible de créer des codes d'erreur personnalisés avec des descriptions en utilisant le bloc Raise Error dans l'éditeur de BP. Un exemple de ce processus est présenté ci-dessous :
Dans ce cas, si la requête vers le point de terminaison associé à la BP ci-dessus échoue, le serveur émettra une erreur 418 contenant le texte de l'erreur lors de l'exécution de la requête . DB: Create Candidate block. Le code d'erreur dans cet exemple peut être celui que l'utilisateur spécifie.
Remarque : le code de réponse d'erreur client HTTP 418 I'm a teapot indique que le serveur refuse de préparer du café parce qu'il est, en permanence, une théière. Une cafetière/théière combinée qui est temporairement à court de café devrait plutôt renvoyer 503. Cette erreur est une référence à Hyper Text Coffee Pot Control Protocol définie dans les blagues du poisson d'avril 1998 et 2014.