Corso sulla documentazione API con Swagger

Lezione 1 • Panoramica degli standard di documentazione

Passa in rassegna i principali formati di specifica delle API, tra cui OpenAPI, RAML e API Blueprint. Posiziona OpenAPI come standard dominante del settore per il resto del corso.

Lezione 2 • Configurazione dell'ambiente di documentazione

Guida gli studenti nell'installazione degli strumenti e nella configurazione di uno spazio di lavoro locale. Garantisce che ogni studente disponga di un ambiente funzionante prima di scrivere qualsiasi specifica.

Lezione 3 • Cosa sono le API e come funzionano

Tratta REST, metodi HTTP, richieste e risposte a livello concettuale. Stabilisce il vocabolario tecnico necessario per tutto il corso.

Lezione 1 • Convalida della prima specifica

Utilizza Swagger Editor e validatori CLI per verificare la correttezza della specifica. Gli studenti correggono errori di convalida reali e comprendono il feedback del parser.

Lezione 2 • YAML e JSON per OpenAPI

Insegna la sintassi YAML, le regole di indentazione e gli equivalenti JSON utilizzati nei file OpenAPI. Previene gli errori di formattazione che bloccano i parser delle specifiche.

Lezione 3 • Struttura del documento OpenAPI

Analizza i campi di primo livello: openapi, info, servers, paths e components. Gli studenti comprendono come ciascun campo contribuisce a una specifica completa.

Lezione 4 • Descrizione delle risposte

Spiega come documentare codici di risposta, header e schemi del corpo. Collega una documentazione accurata delle risposte a una generazione affidabile del codice client.

Lezione 1 • Concetti fondamentali di JSON Schema

Introduce tipi, proprietà, campi obbligatori e vincoli in JSON Schema. Fornisce il vocabolario di modellazione utilizzato in tutto il lavoro successivo sugli schemi.

Lezione 2 • Documentare modelli di dati reali

Applica le competenze sugli schemi a oggetti di dominio realistici come utenti, ordini e prodotti. Rafforza le decisioni di modellazione attraverso esercizi pratici end-to-end.

Lezione 3 • Componenti riutilizzabili e riferimenti

Dimostra la parola chiave $ref e la sezione components/schemas per una documentazione DRY. Gli studenti rifattorizzano gli schemi inline in definizioni condivise e riutilizzabili.

Lezione 4 • Vincoli e parole chiave di convalida

Tratta i vincoli numerici, stringa e array che garantiscono l'integrità dei dati. Gli studenti scrivono schemi che rifiutano payload non validi a livello di specifica.

Lezione 1 • Documentare i flussi di autenticazione

Guida alla documentazione degli endpoint di acquisizione, aggiornamento e revoca dei token. Garantisce che i consumatori comprendano l'intero ciclo di vita dell'autenticazione dalla sola specifica.

Lezione 2 • Corpo della richiesta e tipi di contenuto

Documenta corpi di richiesta JSON, form e multipart con dettagli di codifica. Collega la scelta del tipo di contenuto alla corretta configurazione di schema e codifica.

Lezione 3 • Tipi di parametri in dettaglio

Tratta i parametri di percorso, query, header e cookie con le regole di serializzazione. Gli studenti evitano definizioni di parametri ambigue che confondono i consumatori dell'API.

Lezione 4 • Applicare la sicurezza alle operazioni

Mostra come associare i requisiti di sicurezza a livello globale e per singola operazione. Gli studenti documentano API a sicurezza mista, dove alcuni endpoint sono pubblici e altri protetti.

Lezione 1 • Approfondimento su Swagger Editor

Esplora le funzionalità di convalida in tempo reale, completamento automatico e anteprima di Swagger Editor. Gli studenti utilizzano l'editor in modo efficiente per scrivere ed eseguire il debug delle specifiche.

Lezione 2 • Branding e stili personalizzati

Applica CSS personalizzati e iniezione del logo per allineare Swagger UI alle linee guida del brand. Gli studenti forniscono un portale di documentazione dall'aspetto professionale.

Lezione 3 • Testare le API tramite Swagger UI

Utilizza la funzione Try It Out per eseguire chiamate API live dalla documentazione. Gli studenti verificano che la propria specifica rifletta accuratamente il comportamento reale dell'API.

Lezione 4 • Distribuzione di Swagger UI

Tratta le opzioni di distribuzione npm, CDN e Docker per Swagger UI. Gli studenti ospitano un sito di documentazione funzionante da un ambiente locale o cloud.

Lezione 1 • Callback e webhook

Tratta gli oggetti callback per documentare notifiche push asincrone e webhook. Gli studenti documentano API guidate dagli eventi insieme ai tradizionali pattern richiesta-risposta.

Lezione 2 • Nuove funzionalità di OpenAPI 3.1

Evidenzia il pieno allineamento con JSON Schema, i webhook e le modifiche al dialetto dello schema nella versione 3.1. Gli studenti migrano le specifiche 3.0 esistenti per sfruttare le nuove funzionalità.

Lezione 3 • Estensioni delle specifiche

Introduce i campi di estensione x- per aggiungere metadati specifici del fornitore alle specifiche. Gli studenti estendono OpenAPI senza compromettere la compatibilità con gli strumenti standard.

Lezione 4 • Gestione del versionamento nelle specifiche

Tratta le strategie di versionamento tramite URL, header e tipo di contenuto nei documenti OpenAPI. Gli studenti documentano più versioni di API senza duplicare interi file di specifica.

Lezione 1 • Introduzione alla generazione del codice

Spiega come i generatori analizzano le specifiche OpenAPI per produrre codice specifico per linguaggio. Gli studenti comprendono la relazione tra la qualità della specifica e la qualità del codice generato.

Lezione 2 • Server mock da specifiche

Genera server mock utilizzando Prism e Stoplight per consentire lo sviluppo parallelo. Gli studenti sbloccano i team frontend prima che l'implementazione backend sia completata.

Lezione 3 • Generazione di SDK client

Guida alla generazione di client TypeScript, Python e Java utilizzando OpenAPI Generator. Gli studenti producono librerie client funzionali direttamente dalle proprie specifiche.

Lezione 4 • Contract testing con le specifiche

Utilizza strumenti come Dredd e Schemathesis per convalidare le API rispetto alle loro specifiche OpenAPI. Gli studenti rilevano le violazioni del contratto prima che raggiungano la produzione.

Lezione 1 • Controllo di versione per le specifiche

Applica i flussi di lavoro di branching, tagging e pull request di Git ai file OpenAPI. Gli studenti gestiscono la cronologia delle specifiche con lo stesso rigore applicato al codice sorgente.

Lezione 2 • Governance e guide di stile

Crea regole organizzative per la denominazione, la formattazione e la strutturazione dei file OpenAPI. Gli studenti applicano la coerenza tra più API e team utilizzando il linting automatizzato.

Lezione 3 • Automazione delle pipeline di documentazione

Costruisce pipeline CI/CD che convalidano, generano e pubblicano la documentazione a ogni commit. Gli studenti eliminano i passaggi manuali di documentazione che introducono disallineamenti ed errori.

Lezione 4 • Approcci spec-first e code-first a confronto

Confronta la progettazione della specifica prima della codifica con la generazione di specifiche da annotazioni. Gli studenti scelgono l'approccio giusto in base alla struttura del team e alla fase del progetto.