Swagger e OpenAPI: il manuale d'uso delle tue API

Categoria: Web Development | Livello: Principiante–Intermedio

---

Il problema: le API senza documentazione

Immagina di ricevere un nuovo progetto con una REST API già sviluppata. Nessun README, nessun commento nel codice. Come scopri quali endpoint esistono? Che parametri accettano? Cosa restituiscono in caso di errore?

Questo scenario, purtroppo comune nel mondo reale, è esattamente il problema che Swagger e lo standard OpenAPI sono nati per risolvere.

---

Cos'è Swagger?

Swagger è un insieme di strumenti open source per progettare, documentare e testare API REST. Nasce nel 2010 come progetto indipendente e diventa rapidamente lo standard de facto per la documentazione delle API.

Nel 2015 Swagger viene donato alla OpenAPI Initiative (sotto l'egida della Linux Foundation) e la specifica viene rinominata OpenAPI Specification (OAS). Da quel momento:

• OpenAPI è lo standard (la specifica formale)
• Swagger è il brand degli strumenti (editor, UI, codegen...)

Nella pratica, i due termini vengono spesso usati come sinonimi. Quando si parla di "file Swagger" si intende un file scritto secondo la specifica OpenAPI.

> 💡 In breve: OpenAPI è lo standard, Swagger sono gli strumenti. Come dire che JSON è il formato e Jackson è la libreria per leggerlo.

---

Cos'è la OpenAPI Specification?

La OpenAPI Specification (OAS) è un formato standard, scritto in YAML o JSON, che descrive un'API REST in modo completo e leggibile sia dagli umani che dalle macchine.

Un file OpenAPI descrive:

• Gli endpoint disponibili (/studenti, /studenti/{id}, ...)
• I metodi HTTP supportati (GET, POST, PUT, DELETE, ...)
• I parametri di ogni operazione (path, query, header, body)
• I formati di risposta con i relativi codici HTTP
• I meccanismi di autenticazione (API key, OAuth2, JWT...)
• I modelli dati (schemi JSON degli oggetti)

La versione più diffusa oggi è OpenAPI 3.x (la 3.1.0 è l'ultima stabile).

---

Struttura di un file OpenAPI

Vediamo la struttura di un file YAML OpenAPI per una semplice API di gestione studenti.

openapi: 3.0.3

info:
  title: API Studenti
  description: API REST per la gestione degli studenti scolastici
  version: 1.0.0
  contact:
    name: Filippo Bilardo
    url: https://filippobilardo.it

servers:
  - url: https://api.scuola.it/v1
    description: Server di produzione
  - url: http://localhost:8080/v1
    description: Server di sviluppo locale

paths:
  /studenti:
    get:
      summary: Elenca tutti gli studenti
      description: Restituisce la lista completa degli studenti, con filtro opzionale per classe.
      parameters:
        - name: classe
          in: query
          description: Filtra per classe (es. 4A)
          required: false
          schema:
            type: string
            example: "4A"
      responses:
        "200":
          description: Lista degli studenti restituita con successo
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Studente"
        "500":
          description: Errore interno del server

    post:
      summary: Aggiunge un nuovo studente
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StudenteInput"
      responses:
        "201":
          description: Studente creato con successo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Studente"
        "400":
          description: Dati non validi nel body della richiesta

  /studenti/{id}:
    get:
      summary: Recupera uno studente per ID
      parameters:
        - name: id
          in: path
          required: true
          description: ID univoco dello studente
          schema:
            type: integer
            example: 42
      responses:
        "200":
          description: Studente trovato
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Studente"
        "404":
          description: Studente non trovato

    delete:
      summary: Elimina uno studente
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: Studente eliminato con successo
        "404":
          description: Studente non trovato

components:
  schemas:
    Studente:
      type: object
      properties:
        id:
          type: integer
          example: 42
        nome:
          type: string
          example: "Giulia"
        cognome:
          type: string
          example: "Ferrari"
        classe:
          type: string
          example: "4A"
        media:
          type: number
          format: float
          example: 8.2
      required:
        - id
        - nome
        - cognome

    StudenteInput:
      type: object
      properties:
        nome:
          type: string
          example: "Marco"
        cognome:
          type: string
          example: "Rossi"
        classe:
          type: string
          example: "4B"
        media:
          type: number
          format: float
          example: 7.5
      required:
        - nome
        - cognome

Anatomia del file — sezione per sezione

---

I codici di risposta HTTP più comuni nelle API

Un file OpenAPI documenta esplicitamente i codici di risposta. Ecco i più usati:

---

Gli strumenti Swagger

La specifica OpenAPI è solo un file di testo. Il suo valore si esprime attraverso gli strumenti dell'ecosistema Swagger.

Swagger Editor

Disponibile online su editor.swagger.io, permette di scrivere e validare in tempo reale un file OpenAPI. Il pannello sinistro mostra il codice YAML, quello destro la documentazione interattiva generata automaticamente.

📝 Scrivi YAML → 👁️ Anteprima live → ✅ Validazione automatica degli errori

Swagger UI

Genera una interfaccia web interattiva a partire da un file OpenAPI. Gli sviluppatori possono:

• Sfogliare tutti gli endpoint disponibili
• Leggere la descrizione di parametri e risposte
• Eseguire richieste HTTP direttamente dal browser (Try it out)

Swagger UI può essere integrato in qualsiasi applicazione web o server.

Swagger Codegen / OpenAPI Generator

Genera automaticamente codice client o server a partire dalla specifica. Supporta decine di linguaggi: Python, Java, JavaScript, C#, PHP, Go, Kotlin...

# Genera un client Python dalla specifica
openapi-generator-cli generate \
  -i api-studenti.yaml \
  -g python \
  -o ./client-python

---

Integrare Swagger UI in un progetto Python (Flask)

Vediamo come aggiungere documentazione interattiva a una semplice API Flask.

pip install flask flask-swagger-ui

from flask import Flask, jsonify
from flask_swagger_ui import get_swaggerui_blueprint

app = Flask(__name__)

# Configurazione Swagger UI
SWAGGER_URL = "/docs"          # URL dove sarà visibile la documentazione
API_URL = "/static/swagger.yaml"  # Percorso al file OpenAPI

swagger_ui_blueprint = get_swaggerui_blueprint(
    SWAGGER_URL,
    API_URL,
    config={"app_name": "API Studenti"}
)
app.register_blueprint(swagger_ui_blueprint, url_prefix=SWAGGER_URL)

# Dati di esempio in memoria
studenti = [
    {"id": 1, "nome": "Giulia", "cognome": "Ferrari", "classe": "4A", "media": 8.2},
    {"id": 2, "nome": "Marco",  "cognome": "Rossi",   "classe": "4A", "media": 7.5},
    {"id": 3, "nome": "Luca",   "cognome": "Bianchi", "classe": "4B", "media": 6.9},
]

@app.route("/v1/studenti", methods=["GET"])
def get_studenti():
    return jsonify(studenti), 200

@app.route("/v1/studenti/<int:id>", methods=["GET"])
def get_studente(id):
    studente = next((s for s in studenti if s["id"] == id), None)
    if studente is None:
        return jsonify({"errore": "Studente non trovato"}), 404
    return jsonify(studente), 200

if __name__ == "__main__":
    app.run(debug=True)

Dopo aver salvato il file swagger.yaml nella cartella static/, avvia il server e naviga su http://localhost:5000/docs per vedere la documentazione interattiva.

---

Design-first vs Code-first

Esistono due approcci principali all'uso di OpenAPI:

Code-first (approccio classico)

Si scrive prima il codice, poi si genera o si scrive manualmente la documentazione. Rischio: la documentazione rimane indietro rispetto al codice.

Scrivi il codice → Aggiungi annotazioni → Genera il file OpenAPI

Design-first (approccio consigliato)

Si progetta prima la specifica OpenAPI come "contratto" tra frontend e backend, poi si implementa il codice. Vantaggi: team frontend e backend possono lavorare in parallelo.

Scrivi il file OpenAPI → Genera stub del server → Implementa la logica

> 💡 Best practice: Il design-first è preferibile nei team dove frontend e backend sono sviluppati separatamente. Il contratto OpenAPI diventa il punto di accordo tra le due squadre.

---

Perché OpenAPI è importante per uno studente

Imparare a leggere e scrivere file OpenAPI non è solo un'abilità tecnica: è un linguaggio comune tra sviluppatori, tecnici e anche product manager.

Ecco perché vale la pena apprenderlo:

• Le API pubbliche più importanti (Stripe, Twilio, GitHub, OpenAI...) forniscono la loro specifica OpenAPI
• Molti strumenti di test (Postman, Insomnia) importano direttamente file OpenAPI
• I sistemi di CI/CD possono validare automaticamente che le API rispettino il contratto
• Genera codice client in qualsiasi linguaggio, evitando errori di integrazione

---

Esercizi proposti

Esercizio 1 — Base Apri editor.swagger.io e modifica l'esempio precaricato (PetStore). Aggiungi un nuovo endpoint GET /pets/{id}/vaccini che restituisce la lista dei vaccini di un animale. Definisci uno schema Vaccino con i campi nome, data e scadenza.

Esercizio 2 — Intermedio Scrivi da zero un file OpenAPI 3.0 per un'API di una biblioteca scolastica. Deve prevedere almeno: GET /libri, POST /libri, GET /libri/{id}, POST /prestiti, DELETE /prestiti/{id}. Definisci gli schemi Libro e Prestito nella sezione components. Valida il file con Swagger Editor.

Esercizio 3 — Avanzato Implementa in Python (Flask o FastAPI) l'API della biblioteca dell'esercizio 2. Integra Swagger UI per la documentazione interattiva. Usa la specifica OpenAPI come punto di partenza e verifica che ogni endpoint rispetti esattamente i codici HTTP e i formati definiti nel file YAML.

---

Riepilogo

---

Risorse per approfondire

• 📖 Specifica OpenAPI 3.1 ufficiale
• 🛠️ Swagger Editor online
• 🎨 Swagger UI su GitHub
• ⚙️ OpenAPI Generator
• 🐍 FastAPI — genera OpenAPI automaticamente da Python

---

Articolo pubblicato su filippobilardo.it — Tutti i diritti riservati