Swagger è uno strumento speciale che compone automaticamente il RESTful API documento dell'applicazione.
Il suo vantaggio sta nel fatto che consente non solo di esaminare tutti gli endpoint dell'applicazione, ma anche di testarli immediatamente in azione, inviando una richiesta e ricevendo una risposta.
Per accedere a Swaggerè necessario premere il pulsante Preview nell'applicazione pubblicata e fare clic sul nome del piano di pubblicazione desiderato (Deploy Plan).
Nella nuova finestra aperta viene visualizzato un elenco degli endpoint disponibili e dei metodi associati a tali endpoint. Alcune richieste sono disponibili solo per determinati gruppi di utenti autorizzati (si veda la sezione Middleware del campo Auth module per ogni specifica richiesta nella sezione Endpoints ). A Bearer Token è necessario per le richieste consentite solo agli utenti autorizzati.
Si può accedere all'endpoint corrispondente direttamente in Swagger per ottenere questo token (Auth sezione, POST /auth richiesta).
Premere Try it out e inserire login e password per ottenere un token.
La richiesta sarà inviata su Execute. Se è andata a buon fine, verrà visualizzato un campo token con il valore Bearer token valore.
Il secondo modo per ottenere un token utente autorizzato è che il token si trova nel corpo della richiesta dell'applicazione distribuita.
- Premere F12 nel browser web per aprire lo strumento per gli sviluppatori.
- Inviare una richiesta qualsiasi nell'applicazione distribuita (per aggiornare le tabelle, ad esempio). L'utente che invia la richiesta deve essere autorizzato ad accedere a questo endpoint.
- Aprire la Network e trovare la richiesta corrispondente.
- Andare su Headers e trovare Request Headers sezione. Bearer token sarà presentata sotto Authorization.
Fornire Bearer token a Swagger premendo Authorize e incollando il valore copiato nel passaggio precedente.
Per le richieste di test, selezionare il gruppo desiderato e il metodo che si desidera eseguire. Premere Try it out e compilare i parametri di input della richiesta. Fare clic su Execute per eseguire la risposta.
La risposta più attesa, se la richiesta viene elaborata correttamente dal server, ha il codice 200 e mostra come dovrebbe essere la struttura della risposta.
401 - la richiesta non è stata completata con successo perché il token di autorizzazione richiesto è mancante o non valido.
404 - la richiesta è stata elaborata correttamente, ma la risorsa richiesta non è stata trovata.
422 - sono stati passati parametri errati all'input della richiesta.
500 - errore di elaborazione della richiesta da parte del server.
Sollevare un errore personalizzato
Per i BP personalizzati e le relative richieste, è possibile creare codici di errore personalizzati con descrizioni utilizzando il blocco Raise Error nell'editor dei BP. Un esempio di questo processo è riportato di seguito:
In questo caso, se la richiesta all'endpoint associato al BP di cui sopra fallisce, il server emetterà un errore 418 contenente il testo dell'errore durante l'esecuzione del file DB: Create Candidate block. Il codice di errore in questo esempio può essere qualsiasi codice specificato dall'utente.
Nota: il codice di risposta HTTP 418 I'm a teapot client error indica che il server si rifiuta di preparare il caffè perché è, permanentemente, una teiera. Una caffettiera/teiera combinata che è temporaneamente senza caffè dovrebbe invece restituire 503. Questo errore è un riferimento a Hyper Text Coffee Pot Control Protocol definito in un pesce d'aprile del 1998 e del 2014.
