Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
La specifica OpenAPI, in precedenza nota come Swagger, descrive vari aspetti di un'API. Una specifica OpenAPI (specifica) descrive gli endpoint, i parametri e le risposte dell'API. Le specifiche OpenAPI sono scritte in YAML o JSON e vengono usate dagli strumenti per generare documentazione, test case e librerie client. Avendo una specifica OpenAPI, i generatori di API possono garantire che l'API sia descritta in modo accurato, più accessibile e più semplice da integrare in un'ampia gamma di applicazioni e servizi.
Ecco perché è consigliabile avere una specifica OpenAPI per l'API:
- Documentare un'API in modo standardizzato. Documentare una specifica API in un formato coerente e leggibile.
- Generare un SDK client. Usare strumenti come Kiota per automatizzare la generazione di librerie client in vari linguaggi di programmazione.
- Creare un'API fittizia. Creare server fittizi basati sulla specifica dell'API, che aiutano durante le prime fasi di sviluppo quando l'API effettiva non è ancora implementata.
- Migliorare la collaborazione. Fornire team diversi (front-end, back-end, controllo di qualità) con una chiara comprensione delle funzionalità e delle limitazioni dell'API, che aiutano i nuovi membri del team a diventare rapidamente coinvolti.
- Semplificare i test e la convalida. Automatizzare la convalida delle richieste e delle risposte api in base alla specifica, semplificando così l'identificazione delle discrepanze.
- Eseguire l'integrazione con gli strumenti di gestione API. Integrare, distribuire e monitorare facilmente le API con molti strumenti e gateway di gestione API, ad esempio Centro API di Azure e Gestione API di Azure.
- Semplificare la configurazione del gateway API. Usare le specifiche OpenAPI per configurare i gateway API e automatizzare attività come routing, trasformazioni e impostazioni di condivisione delle risorse tra le origini.
Usando le specifiche OpenAPI, è possibile creare API ben progettate e documentate in modo coerente. Sono anche più gestibili e più facili da usare sia internamente che da consumer esterni.
Non si dispone ancora di una specifica OpenAPI?
La scrittura manuale di una specifica per un'API già esistente richiede tempo e si discosta da ciò che l'API fa realmente. Un'altra opzione consiste nel registrare ciò che l'API restituisce e generare la specifica da tale.
| Avvicinarsi | Cosa ottieni | A cosa prestare attenzione |
|---|---|---|
| Scrivilo a mano | Controllo completo sulle descrizioni ed esempi | Ci vuole tempo e si discosta dall'API reale |
| Generalo dalle annotazioni del codice | Specifica che rimane sincronizzata con il codice | È necessario avere accesso al codice dell'API e il framework deve supportarlo |
| Generarlo dal traffico registrato | Una specifica per qualsiasi API che è possibile chiamare, incluse quelle di cui non si è proprietari | Copre solo le richieste registrate, quindi usa le parti dell'API necessarie |
Dev Proxy registra le richieste e le risposte tra l'app e un'API e genera una specifica OpenAPI da esse. Per i passaggi, vedere Generare una specifica OpenAPI.
Passo successivo
Collabora con noi su GitHub
L'origine di questo contenuto è disponibile in GitHub, in cui è anche possibile creare ed esaminare i problemi e le richieste pull. Per ulteriori informazioni, vedere la guida per i collaboratori.
