Termini Swagger e OpenAPI

Mentre scrivevo il precedente articolo, mai pubblicato, mi sono reso conto che molti non capiscono la differenza tra i termini Swagger e OpenAPI (OAS) . Le persone usano entrambi i termini in modo intercambiabile. Non li biasimo poiché avevo gli stessi dubbi.

Swagger ti consente di descrivere la struttura delle tue API in modo che le macchine possano leggerle.
— SwaggerIO

Se provi a google Swagger o OpenAPI , nella maggior parte dei casi finirai su SwaggerIO , il sito web ufficiale di Swagger. Se me lo chiedi, il sito web ha oscurato lo scopo di Swagger sin dal primo giorno. Non intenzionalmente, però. Le informazioni non mancano, semplicemente non sono presentate in modo chiaro e conciso.

La specifica OpenAPI (OAS) definisce un'interfaccia standard indipendente dal linguaggio per le API RESTful che consente sia agli utenti che ai computer di scoprire e comprendere le funzionalità del servizio senza accedere al codice sorgente, alla documentazione o attraverso l'ispezione del traffico di rete.
— SwaggerIO

Oggi ci sono molti articoli su questo argomento, quindi è molto più facile capire la differenza, ma è ancora possibile trovare scritti che mescolano i termini. SwaggerIO sta promuovendo Swagger come set di strumenti e OpenAPI come specifica. Potremmo dire che lo Swagger viene utilizzato per creare la specifica OpenAPI . In sostanza, questa affermazione non è sbagliata, ma non è tutta la verità.

Uso dei termini

Di solito, gli sviluppatori usano il termine Swagger in almeno due contesti:

• per descrivere un insieme di strumenti per implementare la specifica. Alcuni strumenti sono Swagger Editor, Swagger UI, Swagger Codegen, ecc. È un ecosistema.
• per descrivere la specifica della versione 2.*.*

Gli sviluppatori usano il termine OpenAPI Specification 3 principalmente in un unico contesto:

• per descrivere la specifica della versione 3.*.*. La comunità fa riferimento a OAS, OAS3, OpenAPI Spec, OpenAPI 3 Specification, ecc. Hanno adottato OpenAPI 3 come successore di Swagger Specification 2.

Swagger e OpenAPI sono amici intimi per un motivo. La storia è l'ingrediente chiave qui.

La società SmartBear mantiene Swagger. Nel novembre 2015, The Linux Foundation ha annunciato che sta creando, insieme a SmartBear, Google, Microsoft, Paypal e poche altre società, una nuova organizzazione, OpenAPI Initiative. Il compito principale dell'iniziativa era estendere la specifica Swagger.

Pochi mesi dopo, l'iniziativa ha rinominato Swagger in base alla specifica OpenAPI. L'iniziativa ha clonato il codice nel nuovo repository. Da quel momento, le persone hanno usato entrambi i termini in vari contesti.

Ultima parola

Swagger era un all-in-one, specifiche e set di strumenti. Oggi, Swagger è un set di strumenti. OpenAPI è una specifica. Questo è tutto.

È bello sapere la differenza. Tuttavia, qualunque termine tu usi, l'altra parte ti capirà - alla fine, questa è l'unica cosa che conta.