Vai al contenuto
Home » Notes » Come Documentare una API REST con Swagger (OpenAPI)

Come Documentare una API REST con Swagger (OpenAPI)

copertina guida su come documentare e descrivere una api restful con swagger openapi in yaml

In questa guida tutorial voglio spiegarti come documentare una API REST con Swagger, rispettando lo standard OpenAPI. Che tu abbia bisogno di documentare una vera API che hai appena pubblicato o che tu stia semplicemente studiando l’argomento in qualche corso universitario oppure online, questa guida vuole essere un punto di riferimento per spiegarti come documentare e scrivere una API REST con Swagger, secondo lo standard Open API. Guarda attentamente anche gli esempi, sono molto esplicativi. Iniziamo subito!

Guida completa su come documentare una API REST con Swagger e la specifica OpenAPI

Cos’è Swagger?
Iniziamo dalle basi. Swagger (link: swagger.io) è una piattaforma che mette a disposizione un set di strumenti per scrivere e documentare la struttura delle tue API rispettando lo standard OpenAPI. Questo consente di uniformare le specifiche di tutte le API, permettendo di generare automaticamente documentazioni complete, belle, test interattivi e tanto altro.

Cos’è la specifica OpenAPI?
La specifica OpenAPI (OAS) è un progetto collaborativo donato alla Linux Foundation, che definisce una interfaccia standard per tutte le API RESTful permettendo a macchine e umani di comprendere in maniera semplice le caratteristiche di ogni API, usare strumenti di generazione del codice, di test e tanto altro.

Editor di Swagger

L’editor di Swagger è lo strumento più utilizzato per scrivere documentazioni di API RESTful. É gratuito, e puoi raggiungerlo a questo link. L’editor visuale è composto da due parti, sulla porzione sinistra dello schermo c’è il vero e proprio editor del codice, mentre sul lato destro viene visualizzata in tempo reale l’anteprima.

screenshot swagger editor openAPI descrizione di una API

L’output di questo editor è un file YAML che puoi anche convertire in JSON, infatti YAML (che sta per Yaml Ain’t a Markup Language e si pronuncia “yamel”) è un superset di JSON.

Scrivere la Documentazione dell’API

swagger

Swagger è il primo tag che dovrai utilizzare, e indica la versione di Swagger che la tua documentazione intende usare. La versione più recente è la 2.0.

info

Il tag info contiene una serie di altri tag con le informazioni principali sulla tua API come il titolo, la versione, una breve descrizione, il link ai termini di servizio, l’informazione di contatto e la licenza sotto la quale la tua API è distribuita.

host

Il tag host contiene solo l’indirizzo dell’host al quale la tua API è raggiungibile.

scheme

il tag scheme descrive il protocollo da usare con la tua API. Tipicamente http, htpps o entrambi.

basePath

il tag basePath è il prefisso URL che segue l’indirizzo host. É errato inserire il carattere di slash (“/”) finale, mentre è obbligatorio inserirlo all’inizio. Puoi anche lasciare questo campo vuoto. Scrivere ad esempio:

significa che la tua API è disponibile all’URL “http://api.example.com/v1” e anche allo stesso indirizzo con protocollo https.

tags

Le funzionalità fornite dalla tua API possono essere suddivise per “tags”. É un po’ come dare una categoria ad un insieme di operazioni fornite dalla tua API. Per ognuno di questi tag puoi specificare una breve descrizione e un link di riferimento per ulteriori informazioni.

definitions

le definitions sono le descrizioni degli oggetti con cui lavora la tua API. Contiene la descrizione di questi oggetti, il type (object o array di objects), le loro proprietà e tutti i dettagli sulle proprietà.

Nell’esempio stiamo definendo un tipo di oggetto “Immagine” con le proprietà id, url e categorie. Quest’ultima proprietà è un array di oggetti di tipo “Categoria”, definito sotto con le proprietà nome e score.

paths

Il tag paths contiene la descrizione di tutte le funzionalità e operazioni permesse dalla tua API.
Per ogni funzionalità dovrai specificare:

  • il percorso (path) al quale essa è raggiungibile, ovvero l’indirizzo da inserire nella chiamata API per ottenere quella funzionalità.
  • il metodo HTTP: post, put, get o delete
  • summary: una descrizione breve e opzionalmente anche una più dettagliata
  • operationId: l’operationId che identifica univocamente l’operazione. Deve essere unica in tutta l’API
  • parameters: i parametri in input che vanno forniti nella chiamata API, essi hanno generalmente i seguenti tags:
    • in: il parametro si trova nell’indirizzo della richiesta API, nel body della richiesta o nella query
    • name: nome del parametro
    • required: true o false a seconda che sia obbligatorio l’input del parametro o meno
    • type/schema: se il parametro è un tipo fondamentale dovrai specificarlo con il tag type. Se invece si tratta di un oggetto dovrai usare il tag schema e referenziare il tipo di oggetto.
  • responses: risposte dell’API in caso di successo e di errore, sotto forma di status code HTTP (200 , 400..)
  • security: quali meccanismi di sicurezza sono richiesti per effettuare questa operazione (autenticazione, ecc)

Nel seguente esempio descriviamo alcune funzionalità di una API con il tag paths. Ho preparato un esempio per ognuno dei metodi HTTP – GET, POST e PUT:

Altri appunti a tema tecnologie web


Fonti:
Swagger e OpenAPI
YAML

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *