Specifiche OpenAPI

La Specifica OpenAPI (originariamente nota come Specifica Swagger) è una specifica per file di interfaccia leggibili dalle macchine, utilizzata per descrivere, produrre, consumare e visualizzare servizi web RESTful.^[1] Un documento OpenAPI rappresenta una descrizione formale di un'API, che può essere utilizzata da diversi strumenti per generare codice, documentazione, test case e altro ancora.

Uso

Le applicazioni implementate, basandosi su file di interfaccia OpenAPI, possono generare automaticamente la documentazione dei metodi, dei parametri e dei modelli. Questo aiuta a sincronizzare la documentazione, le librerie client e il codice sorgente.

Storia

Sia la specifica che l'implementazione di un framework sono nate come iniziative di Wordnik. Swagger è stato sviluppato dall'uso di Wordnik durante lo sviluppo di Wordnik Developer e della sottostante API. Lo sviluppo di Swagger è iniziato all'inizio del 2010.^[2]

Nel novembre 2015, SmartBear, la società che ha sostenuto Swagger, ha annunciato che stava contribuendo alla creazione di una nuova organizzazione, sotto la sponsorizzazione della Linux Foundation, chiamata OpenAPI Initiative. Una serie di società, incluse Google, IBM e Microsoft, sono soci fondatori.^[3][4] Nello stesso anno, Swagger ha donato la specifica Swagger 2.0 al nuovo gruppo OpenAPI Initiative.^[5] Anche RAML e API Blueprint sono in esame da parte del gruppo.^[6][7]

Il 1º gennaio 2016, la specifica Swagger è stata rinominata OpenAPI ed è stata spostata in un nuovo repository su GitHub.

Il 26 luglio 2017, l'OpenAPI Initiative ha rilasciato la versione 3.0.0 della specifica.^[8] Tra le novità possiamo notare una semplificazione della struttura, con maggiore riutilizzabilità dei componenti; un miglioramento delle definizioni di sicurezza, inclusa la rinominazione dei flussi OAuth 2 per corrispondere alla specifica OAuth2; l'aggiunta delle callback e dei link.^[9]

Il 15 febbraio 2021, l'OpenAPI Initiative ha rilasciato la versione 3.1.0 della specifica.^[10] Le principali modifiche includono l'allineamento con i vocabolari dello schema JSON, l'introduzione di nuovi elementi di primo livello per descrivere i webhook registrati e gestiti fuori banda, il supporto per identificare le licenze API utilizzando l'identificatore standard SPDX, la possibilità di includere descrizioni accanto all'uso dei riferimenti di schema e una modifica che rende l'oggetto PathItems opzionale, semplificando così la creazione di librerie riutilizzabili di componenti.^[11][12][13]

Caratteristiche

La specifica OpenAPI non richiede un linguaggio di programmazione specifico. Inoltre, è estendibile per l'uso con nuove tecnologie e protocolli. Gli strumenti OpenAPI sono generalmente compatibili con le specifiche RESTful e descrivono come un'API è organizzata e come interagisce con gli utenti, facendo uso di strumenti come Swagger UI, Swagger Codegen, Swagger Hub e Swagger Editor. L'architettura di base della specifica si concentra su tre componenti principali:

• Descrizione di un'API
• Definizione dei parametri di un'API
• Documentazione dei metodi di un'API

Versioni

Swagger

• 1.0 (2011)
• 2.0 (2014)

OpenAPI

• 3.0.0 (2017)
• 3.1.0 (2021)