Che cos'è una specifica OpenAPI?

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

Generare una specifica OpenAPI