In questo articolo scopriamo che cos’è OpenAPI e come funziona. Ma prima di addentrarci in questo discorso, voglio parlarti di una cosa importante.
Durante lo sviluppo di un servizio web, che siano delle API, che sia un software web, è altamente probabile che a un certo punto ti sia dovuto porre la domanda: “ma ci sarà un modo per documentare gli endpoint, i metodi che accettano, come invocarli, che parametri sono necessari, quali facoltativi, eccetera eccetera?”.
Ciao mi chiamo Lorenzo Neri e sono un informatico: realizzo contenuti per aiutare le persone a padroneggiare l’arte del nuovo millennio, ovvero l’informatica!
Nella domanda di prima, ci sono svariati punti che rispondono alla domanda: “Che cos’è OpenAPI?”
Ho detto “svariati” perché ce ne sono molti ma molti altri.
L’aspetto legato al “come funziona OpenAPI” è da discutere lungo questo articolo.
Il risultato finale di come funziona OpenAPI
Il problema principale che risolve OpenAPI è quello di avere una documentazione completa e rapida da realizzare per i propri servizi RESTful o in generale le proprie API.
Ma non solo: permette di avere tutto questo in un formato umano.
Ti faccio un esempio lungo per farti capire quante cose ci siano all’interno di questo formato.
Qui, troviamo un endpoint:
Ma non c’è solo l’endpoint. Viene descritto, oltre al suo indirizzo:
- Il metodo con cui invocarlo
- I parametri che accetta in ingresso
- Un esempio di ciò che bisogna fornirgli
- Una descrizione di cosa fa
- Le risposte che offre con tanto di content type, codice di risposta ed eventuali link
E ci è concesso anche provarlo in direttissima:
Possiamo testare l’endpoint stesso e ricevere in tempo “reale” la risposta fornita con tanto di codice e dettagli.
Quindi, abbiamo visto come funziona OpenAPI in linea molto superficiale. Cerchiamo di capire qualche dettagli aggiuntivo sul suo funzionamento.
Cos’altro possiamo fare con le funzioni di OpenAPI
Il funzionamento basilare per cui usiamo OpenAPI l’abbiamo capito: ci serve per produrre una documentazione leggibile, pratica e completa per i nostri servizi RESTful.
Ma si limita solo a questo?
Ovviamente no.
Tramite l’editor, di cui ti lascio il link qui, possiamo anche generare il server e il client per avere una controprova diretta di ciò che sono i meccanismi delle API all’interno del documento stesso.
Insomma, abbiamo tutto ciò che ci serve: documentazione delle API, strumenti che ci permettano di informaticoarle…
Ora, ci resta da capire davvero che cos’è OpenAPI visto che come funziona l’abbiamo (quasi) visto.
Che cos’è davvero OpenAPI
OpenAPI è praticamente un formato senza troppe restrizioni che ci permette di documentare le API: questo l’abbiamo capito.
Questo formato e gli strumenti che ho citato e linkato prima, sono offerti da Swagger.
Tramite il loro sito web, possiamo accedere a una documentazione completa di questo formato, oltre che ad un editor in tempo reale per leggere i file stessi e testare i nostri già che ci siamo.
Il nostro primo file
In sintesi, per produrre un file nel formato OpenAPI, dobbiamo creare un file JSON oppure YAML a nostra discrezione.
Per comodità, per quanto JSON sia pratico, per questo caso d’uso conviene usare YAML.
In linea generale, c’è da ricordarsi che questo formato prevede alcune parole chiave ed è case sensitive.
Ciò detto, creiamo un primo esempio di file OpenAPI con una descrizione del nostro servizio, i nostri server e un endpoint.
openapi: 3.0.0
info:
title: Esempio API
description: Descrizione del nostro servizio
version: 0.2.0
servers:
- url: http://api.example.com/v1
description: Descrizione del primo server
- url: http://staging-api.example.com
description: Descrizione del secondo server
paths:
/users:
get:
summary: Ritorna una lista di utenti
description: Descrizione estesa che può essere in HTML o CommonMark
responses:
'200': # status code
description: Un array JSON dei nomi utenti
content:
application/json:
schema:
type: array
items:
type: string
Ci hai fatto caso che, le descrizioni possono essere fatte addirittura grazie all’HTML e al CommonMark?
Il formato OpenAPI prevede anche questo, ebbene sì.
Per darti una controprova del codice scritto prima, questo è il risultato:
Il primo pezzo della descrizione con i server e l’endpoint lasciato in formato “contratto”, che se estendiamo…
Ho anche il piacere di lasciarti al seguente link il risultato di tutto questo: sia il codice, sia appunto i risultati finali mostrati in questo screenshot.
Chiarito che cos’è OpenAPI e come funziona, è giusto commentare anche le parti di questo piccolo esempio, poiché sono necessarie e minime al funzionamento e all’uso corretto di OpenAPI
Metadata
Ogni definizione, o meglio ogni file descrittivo delle nostre API, deve includere la versione di OpenAPI che stiamo usando, nel nostro caso:
openapi: 3.0.0
Se non sei sicuro della versione da usare, qui trovi quelle disponibili.
La sezione “info” contiene le informazioni principali delle API: un titolo, una descrizione (anche questa possibile realizzarla in HTML e/o CommonMark) e una versione.
Nel nostro caso specifico:
info:
title: Esempio API
description: Descrizione del nostro servizio
version: 0.2.0
Server
I server, insomma: senza di questi non avremmo di certo delle API. Qui specifichiamo gli URL base dei nostri server e una descrizione dettagliata degli stessi, nel caso che stiamo usando in questo articolo:
servers:
- url: http://api.example.com/v1
description: Descrizione del primo server
- url: http://staging-api.example.com
description: Descrizione del secondo server
Tieni a mente poi, che tutti gli endpoint avranno come URL base quello del server selezionato durante la fase di utilizzo!
Path
Niente di trascendentale: qui specifichiamo gli endpoint uno ad uno nei loro dettagli. Specifichiamo il metodo, il path dell’endpoint stesso e il resto come da nostro esempio:
paths:
/users:
get:
summary: Ritorna una lista di utenti
description: Descrizione estesa che può essere in HTML o CommonMark
responses:
'200': # status code
description: Un array JSON dei nomi utenti
content:
application/json:
schema:
type: array
items:
type: string
Quindi, parametri, request body se necessario, i possibili codici HTTP di risposta e il contenuto delle risposte stesse fornite dall’endpoint.
Arrivati a questo punto, abbiamo fatto una grande e completa panoramica di che cos’è OpenAPI e come funziona: ma mi piacerebbe portarti altri punti delle sue specifiche prima di salutarti.
Parametri
Le operazioni che facciamo con gli endpoint potrebbero avere anche dei parametri inseriti nell’URL, come query string, header o addirittura cookie.
Ovviamente, possiamo definire i tipi dei parametri, il formato, se sono opzionali oppure no e tanti altri dettagli. Per esempio:
paths:
/users/{userId}:
get:
summary: Restituisce un utente tramite ID
parameters:
- name: userId
in: path
required: true
description: Descrizione del parametro in CommonMark oppure HTML
schema:
type : integer
format: int64
minimum: 1
responses:
'200':
description: OK
Dettagli aggiuntivi su questa parte li trovi qui.
Request Body
Se un’operazione fa uso di un request body, usiamo la keyword che troviamo in questo esempio:
paths:
/users:
post:
summary: Crea un utente.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
responses:
'201':
description: Creato
Anche qui, troverai dettagli aggiuntivi in merito.
Risposte
Ovviamente sia nelle API, sia nel funzionamento di OpenAPI non possono mancare le risposte: dico bene?
In sintesi, possiamo definire i codici di risposta e lo schema del corpo della risposta stessa.
Gli schemi possono essere definiti inline o via $ref. Per quest’ultimo parametro ti invito a leggere le sue specifiche qui, mentre per un esempio concreto di tutto questo beh… Eccolo qui:
paths:
/users/{userId}:
get:
summary: Restituisce un utente in base all'ID.
parameters:
- name: userId
in: path
required: true
description: L'ID dell'utente da tornare.
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: Un oggetto utente.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
example: 4
name:
type: string
example: Mario Rossi (Un classico no? :D)
'400':
description: Lo user ID specificato non è valido (not a number).
'404':
description: Nessun utente con l'ID specificato è stato trovato.
default:
description: Errore inaspettato
Avrai notato che i codici HTTP delle risposte vanno racchiusi negli apici ma il formato 2.0 di OpenAPI non lo richiede più e tal proposito ti invito a scoprire maggiori dettagli qui.
Autenticazione
Ci sono diversi punti in cui l’autenticazione alle API è necessaria.
All’interno di OpenAPI possiamo specificare anche questo, tramite le parole chiave “securitySchemes” e “security”.
Facciamo un esempio anche qui:
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
Per non farsi mancare nulla, OpenAPI prevede anche tanti altri metodi, o meglio: li supporta.
Quali? I seguenti:
- HTTP: basic, tramite bearer, eccetera
- API key intesa come header o parametro di una query string, oppure nei cookie
- OAuth 2
- OpenID Connect Discovery.
Per maggior dettagli ti invito a scoprirli qui.
Conclusioni su tuuuutte le specifiche
Abbiamo fatto un gran bel discorsone su OpenAPI: abbiamo visto che cos’è, come funziona, un esempio prolungato e diversi campi di applicazione, nonché il fantastico editor per testare direttamente ciò che abbiamo scritto.
Ma ovviamente non posso che salutarti con le specifiche complete, disponibili su GitHub.
Sono a distanza di un singolo click qui.
