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. 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.
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
[modifica | modifica wikitesto]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
[modifica | modifica wikitesto]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]
Il 24 ottobre 2024 viene rilasciata OpenAPI 3.1.1, una patch che non introduce nuove funzionalità ma chiarisce aspetti tecnici e migliora la documentazione: la versione HTML diventa quella ufficiale, vengono precisati riferimenti, termini chiave, uso di URL e Markdown, gestione dei dati e sicurezza; esempi e appendici sono riorganizzati, parte dei contenuti è spostata su Learn OpenAPI ed i tool compatibili con la 3.1.0 restano pienamente validi aggiornando solo il campo openapi.[14]
Caratteristiche
[modifica | modifica wikitesto]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
[modifica | modifica wikitesto]Swagger
[modifica | modifica wikitesto]- 1.0 (2011)
- 2.0 (2014)
OpenAPI
[modifica | modifica wikitesto]- 3.0.0 (2017)
- 3.1.0 (2021)
- 3.1.1 (2024)
Note
[modifica | modifica wikitesto]- ^ Linux Foundation wants to extend Swagger in connected buildings | Business Cloud News, su businesscloudnews.com. URL consultato il 22 aprile 2016 (archiviato dall'url originale il 20 luglio 2018).
- ^ swagger-api/swagger-spec, su GitHub. URL consultato il 1º dicembre 2015.
- ^ SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger, in ProgrammableWeb. URL consultato il 21 aprile 2016 (archiviato dall'url originale il 9 novembre 2016).
- ^ New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services, su linuxfoundation.org. URL consultato il 22 aprile 2016 (archiviato dall'url originale il 27 aprile 2016).
- ^ OpenAPI Specification v3.1.0 | Introduction, Definitions, & More, su spec.openapis.org. URL consultato il 25 marzo 2024.
- ^ Yves de Montcheuil, In 2016, the need for an API meta-language will crystallize, su InfoWorld. URL consultato il 25 aprile 2016.
- ^ Amazon API Gateway Now Supports Swagger Definition Import, su InfoQ. URL consultato il 25 aprile 2016.
- ^ (EN) OpenAPI Initiative, The OAI Announces the OpenAPI Specification 3.0.0, su OpenAPI Initiative, 26 luglio 2017. URL consultato il 13 ottobre 2024.
- ^ What is OpenAPI 3.0? | Swagger Blog, su SmartBear.com. URL consultato il 13 ottobre 2024.
- ^ (EN) Linux com Editorial Staff, OpenAPI Specification 3.1.0 Available Now, su Linux.com, 26 aprile 2021. URL consultato il 13 ottobre 2024.
- ^ (EN) Tyler Charboneau, What’s New in OpenAPI 3.1.0? | Nordic APIs |, su Nordic APIs, 7 aprile 2021. URL consultato il 13 ottobre 2024.
- ^ (EN) OpenAPI Initiative, OpenAPI Specification 3.1.0 Released, su OpenAPI Initiative, 18 febbraio 2021. URL consultato il 13 ottobre 2024.
- ^ (EN) OpenAPI Initiative, Migrating from OpenAPI 3.0 to 3.1.0, su OpenAPI Initiative, 16 febbraio 2021. URL consultato il 13 ottobre 2024.
- ^ (EN) OpenAPI Specification v3.1.1, su spec.openapis.org. URL consultato il 16 giugno 2025.
Bibliografia
[modifica | modifica wikitesto]- F. Haupt, D. Karastoyanova, F. Leymann e B. Schroth, A Model-Driven Approach for REST Compliant Services, ICWS 2014, collana 2014 IEEE International Conference on Web Services, 2014, pp. 129-136, DOI:10.1109/ICWS.2014.30, ISBN 978-1-4799-5054-6.
Voci correlate
[modifica | modifica wikitesto]Collegamenti esterni
[modifica | modifica wikitesto]- (EN) Sito ufficiale, su openapis.org.
- Repository sorgenti di Specifiche OpenAPI, su github.com.
- Swagger website, su swagger.io.
