Hai mai aggiornato un endpoint e scoperto che la documentazione era ancora quella della versione precedente? Succede a tutti. Manuali obsoleti, team che si accorgono degli errori solo in produzione, clienti che chiamano perché un'API si comporta diversamente da quanto scritto. Noi, di Meteora Web, lo vediamo ogni volta che subentriamo su progetti iniziati da altri. La documentazione API è il primo strumento che viene trascurato non appena il progetto accelera.
La soluzione? Smettila di scrivere documenti statici. Usa OpenAPI e Swagger per generare e mantenere la documentazione automaticamente, direttamente dal codice.
Perché la documentazione API diventa obsoleta così in fretta?
Se scrivi a mano la documentazione, stai producendo debito tecnico. Ogni volta che modifichi uno schema, un parametro, un header, devi ricordarti di aggiornare il file docs. In un team di 3 persone si dimentica già la metà delle volte. In un team di 10 è certo che qualcosa sfugga.
Il costo degli errori di comunicazione
Un collega frontend che integra un'API con una risposta sbagliata perde ore. Un cliente che usa un endpoint deprecato senza saperlo rischia crash. Noi abbiamo visto progetti in cui l'unica documentazione era un PDF di 2 anni prima. Risultato: debug selvaggio, produzione bloccata, fatturato perso.
Sponsored Protocol
L'approccio giusto: code-first o spec-first
Ci sono due strade. Code-first: scrivi il codice, poi con strumenti come swagger-php (per Laravel) o SpringDoc (per Java) generi lo spec OpenAPI. Spec-first: scrivi prima lo spec YAML/JSON, poi usi generatori per creare il codice server e client. Noi preferiamo code-first quando il progetto è già avviato, spec-first se lo sviluppiamo da zero. Entrambi funzionano, l'importante è automatizzare la generazione.
Come funziona OpenAPI e perché è lo standard giusto?
OpenAPI è un formato standard (YAML o JSON) per descrivere API REST. Definisce endpoint, parametri, modelli, autenticazione, codici di risposta. Swagger è l'ecosistema di strumenti che lavora su OpenAPI: Swagger UI genera una pagina interattiva, Swagger Editor permette di modificare lo spec, Swagger Codegen crea client SDK.
Esempio di spec OpenAPI 3.1
openapi: '3.1.0'
info:
title: Catalogo Prodotti API
version: 1.0.0
description: API per gestire prodotti e categorie
paths:
/prodotti:
get:
summary: Elenco prodotti
parameters:
- name: categoria
in: query
schema:
type: string
responses:
'200':
description: Lista prodotti
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Prodotto'
components:
schemas:
Prodotto:
type: object
properties:
id:
type: integer
nome:
type: string
prezzo:
type: number
Con uno spec così, Swagger UI genera una pagina con cui i tuoi sviluppatori possono testare gli endpoint direttamente dal browser. Niente più assurdità come "prova su Postman e incolla lo screenshot".
Sponsored Protocol
Come automatizzare la generazione della documentazione nel workflow?
Il vero salto di qualità è integrarlo nella CI/CD. Ogni volta che fai un push, la documentazione viene rigenerata e pubblicata. Non si scorda più.
Sponsored Protocol
Passo 1: annota il codice con i metadati OpenAPI
In PHP con Laravel e swagger-php, usi le annotation (o attributi PHP 8):
use OpenApi\Attributes as OA;
#[OA\Get(path: '/api/prodotti', summary: 'Lista prodotti')]
#[OA\Response(response: 200, description: 'OK', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/Prodotto')))]
public function index() {
return Product::all();
}
Poi generi lo spec con un comando:
vendor/bin/openapi src -o public/spec/openapi.yaml
Passo 2: pubblica la UI statica
Swagger UI è un frontend statico. Puoi copiare i file nella cartella pubblica del tuo server o integrarlo in un subpath. Noi, di Meteora Web, usiamo spesso Redoc per una documentazione più pulita, ma Swagger UI è più interattivo. Entrambi si attivano con una riga di HTML.
Passo 3: CI/CD automatico
In GitHub Actions, aggiungi uno step che genera lo spec e lo pubblica su una branch docs separata o su un servizio come GitHub Pages. Un esempio minimo:
- name: Generate OpenAPI spec
run: vendor/bin/openapi src -o docs/openapi.yaml
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
Ora ogni push aggiorna la documentazione. Il team frontend ha sempre l'ultima versione, senza chiedere a nessuno.
Sponsored Protocol
Quali strumenti usare per documentazione interattiva e test?
Swagger UI
Interfaccia standard: elenca gli endpoint, mostra schemi, permette di eseguire chiamate di test. Ottimo per sviluppo e debug.
Redoc
Più orientato alla lettura. Genera una pagina ben strutturata con navigazione laterale. Ideale per documentazione pubblica da condividere con clienti.
Postman e Newman
Puoi importare lo spec OpenAPI in Postman e usare Newman per eseguire test automatici. Noi lo facciamo per verificare che la risposta corrisponda allo schema.
Come validare automaticamente la spec OpenAPI?
Uno spec scritto male è peggio di nessuna documentazione. Deve essere valido e coerente.
Swagger CLI (sorgente ufficiale)
swagger-cli validate openapi.yaml
Spectral (linting avanzato)
Puoi definire regole personalizzate (es. "ogni endpoint deve avere un summary", "i parametri devono essere camelCase"). Noi lo usiamo nei nostri progetti Laravel per garantire coerenza.
Sponsored Protocol
rules:
summary-in-operations:
severity: error
given: $.paths.*[get,post,put,delete]
then:
field: summary
function: truthy
Cosa fare adesso
Non aspettare che la documentazione diventi un problema. Ecco la checklist operativa per il tuo prossimo sprint:
- Adotta OpenAPI 3.1 – è lo standard più recente con supporto per JSON Schema 2020-12.
- Scegli code-first o spec-first – se hai già il codice, inizia con le annotation; se parti da zero, scrivi lo spec YAML.
- Integra la generazione nella CI – ogni push produce la documentazione aggiornata.
- Valida ogni commit – usa spectral o swagger-cli nel workflow.
- Pubblica con Redoc o Swagger UI – rendila accessibile a tutto il team e ai clienti.
Noi, di Meteora Web, abbiamo automatizzato la documentazione API per progetti WooCommerce, piattaforme su Laravel e app Vue. Il risultato? Meno ticket di supporto, onboarding più veloci per nuovi sviluppatori, API che si possono testare in 5 secondi. Se vuoi vederlo applicato al tuo progetto, troviamo insieme la soluzione.
