Skip to main content
search

Swagger per Starty ERP

Cos’è Swagger UI e Come Utilizzarlo per Documentare e Testare le API

Nel panorama dello sviluppo software, le API (Application Programming Interfaces) giocano un ruolo cruciale nel collegare sistemi, applicazioni e servizi.

Tuttavia, la complessità di un’API può rendere difficile per gli sviluppatori comprenderne le funzionalità o integrarle nei propri progetti, è qui che entra in gioco Swagger UI, uno strumento fondamentale per documentare e testare le API in modo interattivo e intuitivo.

Le API di Starty ERP sono potenti e flessibili, progettate per integrarsi facilmente con le applicazioni client. Seguendo questa guida, puoi configurare correttamente il sistema di autenticazione e accedere alle risorse in modo sicuro ed efficiente.

Se hai domande o vuoi condividere la tua esperienza con l’integrazione delle API di Starty ERP, contattaci utilizzando il form a fine pagina

Cos’è Swagger UI?

Swagger UI è uno strumento open source progettato per generare automaticamente una documentazione interattiva per un’API a partire da una specifica OpenAPI. La specifica OpenAPI, precedentemente conosciuta come Swagger Specification, è uno standard largamente adottato per descrivere le API RESTful in modo uniforme.

Grazie a Swagger UI, gli sviluppatori possono esplorare e testare un’API senza dover scrivere codice aggiuntivo, rendendo la collaborazione tra team più efficiente e il debugging più semplice.

Caratteristiche Principali di Swagger UI

  1. Interfaccia Intuitiva: Swagger UI offre un’interfaccia web user-friendly che elenca tutti gli endpoint disponibili, organizzati in categorie logiche.
  2. Documentazione Dettagliata: Ogni endpoint viene presentato con informazioni dettagliate, come:
    • Metodo HTTP (GET, POST, PUT, DELETE, ecc.)
    • Parametri richiesti e facoltativi
    • Struttura del body della richiesta
    • Possibili risposte con codici di stato (200, 400, 500, ecc.)
  3. Test in Tempo Reale: È possibile eseguire chiamate API direttamente dall’interfaccia, specificando i parametri e visualizzando le risposte. Questo è particolarmente utile per verificare che gli endpoint funzionino come previsto.
  4. Integrazione OpenAPI: Swagger UI è strettamente integrato con OpenAPI, rendendo il processo di documentazione automatizzato e standardizzato.
  5. Open Source e Personalizzabile: Lo strumento è gratuito e può essere personalizzato per soddisfare le esigenze specifiche di un’organizzazione.

Perché Usare Swagger UI?

  • Facilita la Collaborazione: Sviluppatori, tester e stakeholder possono accedere a una visualizzazione chiara delle funzionalità dell’API, migliorando la comunicazione.
  • Riduce gli Errori: La documentazione automatica minimizza le discrepanze tra il codice e le specifiche.
  • Accelera lo Sviluppo: Testare le API direttamente da Swagger UI consente agli sviluppatori di identificare e risolvere rapidamente eventuali problemi.
  • Migliora l’Esperienza Utente: I consumatori dell’API possono comprendere facilmente come utilizzare i vari endpoint, riducendo la curva di apprendimento.

Guida Completa: Configurare e Utilizzare le API di StartyERP v3

Le API di StartyERP offrono un’ampia gamma di funzionalità per l’integrazione e l’accesso alle risorse del sistema tramite un’interfaccia REST con scambio di oggetti JSON. Questo articolo illustra come configurare e utilizzare le API di StartyERP, concentrandosi sul processo di autenticazione tramite JSON Web Token (JWT).

1. URL Base delle API

L’URL base delle API di StartyERP è:

https://api.startyerp.cloud/[sottodominio]/v3/

Esempio: Se il tuo URL di accesso a Starty è:

https://mycompany.startyerp.cloud

L’URL delle API sarà:

https://api.startyerp.cloud/mycompany/v3/

2. Processo di Autenticazione

Ogni richiesta alle API richiede un token di autenticazione valido nel formato JSON Web Token (JWT). Il token si ottiene tramite un processo di handshake.

a) Richiesta di Handshake Iniziale

Inoltra una richiesta all’endpoint /handshake utilizzando l’autenticazione Basic con le credenziali di un utente abilitato.

Richiesta:

POST https://api.startyerp.cloud/[sottodominio]/v3/handshake
User-Agent: MyUserAgent  
Accept: */*  
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Risposta (HTTP 200):

[
  {"roleId": "5001", "roleName": "Amministratore"},
  {"roleId": "5002", "roleName": "Agente"},
  {"roleId": "5003", "roleName": "Operatore"}
]

b) Specifica del Ruolo

Indica il ruolo che desideri utilizzare aggiungendo il parametro r con il valore del roleId.

Richiesta:

POST https://api.startyerp.cloud/[sottodominio]/v3/handshake?r=5003
User-Agent: MyUserAgent  
Accept: */*  
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Risposta (HTTP 200):

[
  {"orgId": "5018", "orgName": "LaMiaOrganizzazione"},
  {"orgId": "5026", "orgName": "AltraOrganizzazione"}
]

c) Specifica dell’Organizzazione

Seleziona l’organizzazione utilizzando il parametro o con il valore del orgId.

Richiesta:

POST https://api.startyerp.cloud/[sottodominio]/v3/handshake?r=5003&o=5018
User-Agent: MyUserAgent  
Accept: */*  
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Risposta (HTTP 200):

{"token": "eyJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50TmFtZS[...]"}

3. Utilizzo del Token

Una volta ottenuto il token, includilo nell’header Authorization per tutte le richieste successive.

Esempio di Richiesta API:

GET https://api.startyerp.cloud/[sottodominio]/v3/[resource]
User-Agent: MyUserAgent  
Accept: application/json, */*  
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50TmFtZS[...]

4. Rigenerazione del Token

Il token scade dopo 7 giorni (default) o in base alla configurazione. Per rigenerare il token:

  • Conserva roleId e orgId in cache.
  • Effettua una singola chiamata all’API con i parametri r (ruolo) e o (organizzazione).

Richiesta di Rigenerazione:

POST https://api.startyerp.cloud/[sottodominio]/v3/[resource]?r=1005&o=1007
User-Agent: MyUserAgent  
Accept: */*  
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

5. Sicurezza

  • Token Protetti: Il contenuto del token è firmato e non può essere manomesso.
  • Ruoli e Permessi: Assicurati che l’utente abbia il ruolo e i permessi appropriati configurati nel sistema.
  • Conservazione dei Token: Salva il token in modo sicuro per evitare accessi non autorizzati.

6. Generatore di Token API

Il Generatore di Token, accessibile dal menu Configurazione di Starty ERP, offre una modalità alternativa per ottenere token con o senza scadenza. È ideale per generare token per utenti dedicati.

Medoti e Connessioni

A questo indirizzo web potrai trovare la Guida completa di Swagger di Starty ERP

The best Erp Cloud Software.
Richiedi una sessione dimostrativa gratuita:

un nostro esperto applicativo ti presenterà le caratteristiche del prodotto. Compila il form sottostante:
Close Menu