OpenAPI and Swagger Ecosystem

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 1 di 19. Le API sono il motore del web moderno, ma come fanno a parlarsi davvero senza infiniti trial and error? Ti serve un modo affidabile per sapere esattamente cosa si aspetta un server e cosa ti restituirà, prima ancora di scrivere una singola riga di codice. Questo meccanismo è il contratto API, governato dalla OpenAPI Specification. La OpenAPI Specification è un'interfaccia standardizzata e language-agnostic per le API REST. Pensala come un blueprint architetturale. Se definita correttamente, sia un umano che una macchina possono guardare questo blueprint e capire esattamente cosa fa un servizio. Non hanno bisogno di accedere al codice sorgente, non devono leggere documentazione in PDF separata e non devono ispezionare il traffico di rete live. La specifica delinea chiaramente gli endpoint disponibili, gli input precisi che richiedono e le strutture esatte dei dati che restituiscono. È scritta in plain text, usando YAML o JSON, il che la rende universalmente leggibile sia dai tool automatizzati che dagli sviluppatori umani. Se lavori con le API, probabilmente avrai sentito il termine Swagger. Spesso le persone usano Swagger e OpenAPI in modo intercambiabile, ma oggi rappresentano concetti completamente diversi. In origine, la specifica stessa si chiamava Swagger. Nel 2015, i creatori hanno donato la specifica alla Linux Foundation, dove è stata ufficialmente rinominata OpenAPI Specification. Oggi, OpenAPI si riferisce strettamente alle regole e allo standard. Swagger si riferisce all'ecosistema di tool commerciali e open source creati da SmartBear che implementano quelle regole. Per esempio, Swagger UI genera documentazione interattiva, e Swagger Editor ti aiuta a scrivere i file. Scrivi un documento OpenAPI, ma potresti usare i tool di Swagger per visualizzarlo. Questo ci porta al vero potere della specifica, ovvero lo sviluppo design-first. Senza un contratto chiaro, lo sviluppo delle API di solito avviene in modo lineare. Il team di backend scrive il codice, espone un nuovo endpoint, e poi consegna della documentazione scritta. Nel frattempo, il team di frontend resta fermo, aspettando che il backend finisca per poter iniziare a collegare la user interface. Ecco il punto chiave. Quando adotti OpenAPI, inverti questo processo. Prima ancora che qualcuno scriva il codice dell'applicazione, entrambi i team si mettono d'accordo sul documento OpenAPI. Questo file di testo diventa un contratto rigoroso che elimina ogni incertezza. Il team di backend lo usa per generare i server stub e validare che la loro implementazione soddisfi i requisiti concordati. Allo stesso tempo, il team di frontend usa l'esatto stesso documento per generare dei mock server. Possono iniziare subito a costruire la user interface, facendo richieste di rete a un backend simulato che si comporta esattamente come farà l'API finale. Nessun team blocca l'altro. Dato che questo contratto è machine-readable, risolve anche in modo definitivo il problema della documentazione obsoleta. Quando un requisito dell'API cambia, aggiorni prima il file della specifica. Il tuo tooling poi rigenera automaticamente la documentazione web, i mock server e le librerie client. La documentazione e il codice restano perfettamente sincronizzati perché condividono una single source of truth. Una API specification non è solo un meccanismo per generare belle pagine web; è un protocollo di comunicazione fondamentale per i tuoi team di engineering che trasforma le assunzioni umane in regole eseguibili. Se ti piace lo show e vuoi supportarci, cerca DevStoriesEU su Patreon. Grazie per l'ascolto. Alla prossima!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 2 di 19. Scrivere la documentazione è un lavoro noioso, ma cosa succederebbe se fosse il tuo codice a scrivere la documentazione e la tua documentazione a scrivere il codice? Questo workflow bidirezionale è la promessa fondamentale dell'ecosistema open-source Swagger. Un errore comune è pensare di dover adottare l'intero ecosistema contemporaneamente. Non è così. Il toolset è completamente modulare. Puoi scegliere i singoli componenti in base alle tue specifiche esigenze di workflow, sia che tu stia semplicemente renderizzando della documentazione esistente, sia che tu stia facendo lo scaffolding di un backend completamente nuovo. I principali tool open-source funzionano come una pipeline. Progetti l'API in Swagger Editor, la visualizzi in Swagger UI e automatizzi le implementazioni usando Swagger Codegen. Swagger Editor è il punto di partenza del design delle API. È un ambiente browser-based in cui scrivi la tua specifica OpenAPI in YAML o JSON. Mentre scrivi, l'editor valida continuamente la tua sintassi rispetto alle regole della specifica OpenAPI. Se posizioni un campo in modo errato o definisci un data type non valido, l'editor segnala immediatamente l'errore. Fornisce una vista split-screen in real-time, mostrando il raw text da un lato e un'anteprima visiva dall'altro. Una volta che il contratto è valido, puoi passare all'automazione con Swagger Codegen. Questo tool prende il tuo file di specifica OpenAPI e lo traduce in codice sorgente funzionante. Supporta decine di linguaggi e framework. Puoi generare dei server stub, che forniscono il routing e i controller boilerplate per il tuo backend. In alternativa, puoi generare dei client SDK, che le applicazioni consumer utilizzano per interagire con la tua API senza dover scrivere logica custom per le richieste HTTP. Poi c'è Swagger UI. Questo tool fa il parsing della tua specifica e la renderizza come una pagina di documentazione interattiva web-based. Va oltre il testo statico. Swagger UI genera input field e bottoni di esecuzione direttamente dalle definizioni della tua API. Gli utenti possono inserire parametri, allegare authentication token, inviare richieste HTTP reali agli endpoint della tua API e ispezionare le risposte direttamente nel browser. Considera un workflow concreto che combina questi tre tool. Inizi in Swagger Editor, redigendo la specifica per una nuova API di user management. Definisci gli endpoint, i request payload e le risposte attese. Una volta completato il contratto, passi quel file a Swagger Codegen, configurandolo per produrre in output un server stub Node.js. Codegen genera automaticamente la struttura delle directory, la configurazione dei package e i route handler. Devi solo scrivere la business logic specifica e le query al database all'interno di quei controller pre-wired. Nel frattempo, dai quello stesso identico file di specifica OpenAPI al tuo team di QA, servito tramite Swagger UI. I QA engineer non hanno bisogno di leggere il tuo file YAML o di guardare il tuo codice Node.js. Aprono la pagina web di Swagger UI, vedono gli input richiesti e iniziano immediatamente a inviare test payload al tuo nuovo server Node.js. Ecco il punto chiave. L'ecosistema open-source Swagger sposta lo sviluppo delle API dallo scrivere codice backend sperando che la documentazione rimanga accurata, al definire prima un contratto rigoroso, in cui la documentazione user-facing e il server boilerplate vengono generati dalla stessa identica source of truth. Questo è tutto per questo episodio. Grazie per l'ascolto e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 3 di 19. Prima di poter mappare un'API complessa, hai bisogno di una tela vuota, ma iniziare con la struttura di base sbagliata romperà silenziosamente l'intera toolchain più avanti. Questo ci porta all'Anatomia di un Documento OpenAPI. Nella sua essenza, un documento OpenAPI è definito rigorosamente come un JSON object. Puoi scrivere il tuo file usando il formato JSON o il formato YAML. Il tooling li supporta entrambi e il data model sottostante rimane esattamente lo stesso. Poiché si mappa direttamente a un JSON object standard, le regole di formattazione sono rigide. Ogni nome di campo è completamente case-sensitive. Se la specifica impone un nome di campo in minuscolo, scriverlo con una lettera iniziale maiuscola significa che il parser lo ignorerà o lancerà un errore. Quando organizzi il tuo progetto, hai una scelta nella struttura del documento. Puoi definire tutto all'interno di un singolo file monolitico. In alternativa, puoi suddividere le tue definizioni in una struttura multi-documento. In un setup multi-documento, un root file funge da entry point e si collega ai file esterni tramite reference pointer. Che tu usi un solo file o cinquanta, il parser alla fine li risolve in un singolo JSON object logico in memoria. Prendiamo uno scenario concreto. Stai iniziando un progetto nuovo di zecca. Crei un file di testo vuoto chiamato openapi punto yaml. Prima di tentare di progettare qualsiasi logica, vuoi stabilire una baseline validata. Per passare uno schema validator, il tuo canvas vuoto deve contenere esattamente due campi a livello root. Il primo campo obbligatorio si chiama openapi. Il suo valore è una string che specifica la versione esatta della OpenAPI Specification che stai usando, ad esempio 3.1.0. È estremamente comune confondere questo campo con la versione della tua API. Sono completamente slegate. La string di versione di openapi esiste esclusivamente per la compatibilità del tooling. Quando un code generator o un documentation viewer apre il tuo file, legge prima questo campo per determinare quali regole di parsing applicare. Se qui dichiari 3.0.0 ma usi feature della 3.1.0, i tuoi tool di validazione falliranno perché stanno valutando il tuo documento contro il rule set sbagliato. Ecco il punto chiave. Il secondo campo root obbligatorio è quello in cui vanno i dettagli effettivi della tua API. Questo campo è l'info object. L'info object fornisce i metadati per la tua applicazione. Non dettaglieremo i suoi contenuti interni qui, se non per dire che richiede un titolo e la sua string di versione. Quella string di versione interna dentro l'info object è dove definisci se la tua applicazione è alla versione uno o alla versione due. Una volta che il tuo file openapi punto yaml contiene solo questi due campi root, openapi e info, hai un documento OpenAPI strutturalmente completo. Puoi passare questo file in un validator in questo momento, e passerà senza problemi. Stabilire questa struttura minima valida garantisce che il tuo parser e la tua toolchain funzionino perfettamente prima di introdurre la complessità della vera e propria routing logic. Grazie per l'ascolto, happy coding a tutti!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 4 di 19. Se la tua API va offline, come fa un consumer a sapere chi contattare? La risposta si trova proprio all'inizio della tua spec. Stiamo parlando di preparare il terreno con Info e Servers. Prima ancora che uno sviluppatore faccia una request o esamini un data model, ha bisogno di contesto. Gli oggetti Info e Server forniscono proprio questo. Pensali come la copertina e la rubrica della tua API. L'oggetto Info è il tuo hub di metadata. Qui due campi sono strettamente obbligatori. Il primo è il title, che è semplicemente il nome human-readable della tua applicazione. Il secondo è la version. Spesso la si confonde con la versione della spec OpenAPI. Sono due cose completamente separate. La versione OpenAPI indica al parser quale set di regole di sintassi seguire. La version di Info è il numero di release della tua API, qualcosa come 1.0.5. Indica al consumer quale iterazione del prodotto sta guardando. Oltre ai campi obbligatori, l'oggetto Info ti permette di aggiungere contesto. Puoi includere una description, che supporta la formattazione CommonMark. Questo ti permette di scrivere una documentazione dettagliata e leggibile, con paragrafi e link, direttamente all'interno della spec. Puoi anche definire un oggetto contact contenente un name, un URL e un indirizzo email. Se qualcosa si rompe o uno sviluppatore ha bisogno di accesso, questo gli dice esattamente dove andare. Infine, l'oggetto license ti permette di specificare i termini legali sotto i quali opera l'API, richiedendo un name e, opzionalmente, un URL che punta al testo della licenza. Una volta che l'oggetto Info stabilisce cos'è l'API, l'array Servers dice al consumer dove si trova. Senza di questo, i consumer sanno cosa fa la tua API, ma non dove trovarla. Devi fornire un array di oggetti Server che rappresentano i diversi ambienti in cui è hostata la tua API. Ogni oggetto Server richiede un singolo campo, ovvero l'URL. Ecco il punto chiave. Non sei limitato a un singolo base URL. Puoi definire diverse entry server per riflettere la tua infrastruttura reale. Ad esempio, il tuo primo oggetto Server potrebbe contenere il tuo URL di production usando un indirizzo HTTPS sicuro, con una description che lo etichetta esplicitamente come ambiente di production live. Il tuo secondo oggetto Server potrebbe puntare a un URL di staging o sandbox, con una description che fa notare che è strettamente per il testing. Quando strutturi i tuoi server in questo modo, i tool di documentazione interattiva e i generatori di client diventano molto più potenti. Invece di costringere uno sviluppatore a configurare manualmente il base URL per ogni request, gli basterà selezionare staging o production da un menu a tendina nella sua interfaccia. I tool fanno il parsing del tuo array servers e instradano automaticamente le request all'host corretto. Puoi anche usare URL relativi se il tuo documento OpenAPI è hostato direttamente sul server che fornisce l'API. Questo rende più facile fare il deploy dell'esatto stesso file di spec su ambienti diversi, senza dover aggiornare costantemente l'indirizzo dell'host. Definire oggetti Info e Server accurati significa che la tua API non è solo una raccolta sparsa di operazioni, ma un servizio completamente identificato, legalmente chiaro e fisicamente localizzabile. La qualità di qualsiasi integrazione automatizzata dipenderà interamente dall'accuratezza di questi base URL. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 5 di 19. Ogni API REST ha bisogno di endpoint, ma come dimostri matematicamente a una macchina quali metodi HTTP sono consentiti e dove? Li mappi logicamente. Oggi vediamo il mapping dei path e delle operation dell'API. Pensa al Paths Object in OpenAPI come al router centrale della tua documentazione. Funziona come una directory che mappa gli URL relativi a funzionalità specifiche. Prima di vedere cosa c'è dentro, dobbiamo chiarire un malinteso comune. I path devono sempre iniziare con uno slash. Sono strettamente relativi alla tua Server URL, mai assoluti. Se la tua API è hostata su api punto example punto com, il tuo path è semplicemente slash users, non il dominio completo. La specifica si basa su questa formattazione esatta per appendere correttamente il path all'indirizzo base del server. All'interno del Paths Object, definisci le singole route usando chiavi di tipo string. Il valore assegnato a ogni chiave della route si chiama Path Item Object. Un Path Item Object è fondamentalmente solo un container. Raggruppa tutti i metodi HTTP consentiti su quello specifico URL. Non stabilisce direttamente input o output. Invece, contiene chiavi che rappresentano i metodi HTTP standard, come get, post, put o delete. Quando mappi uno di questi metodi HTTP all'interno di un Path Item, il valore che gli associ è un Operation Object. L'Operation Object è dove viene definita l'azione vera e propria. Descrive esattamente cosa può fare un client quando invia quello specifico metodo a quel path esatto. Per visualizzare la struttura, considera un endpoint standard per la gestione degli utenti. Nel tuo Paths Object di root, definisci una chiave chiamata slash users. Il valore che gli associ è il tuo Path Item Object. All'interno di quel container, definisci una chiave get e una chiave post. La chiave get contiene un Operation Object che spiega come l'API restituisce una lista di utenti. La chiave post contiene un Operation Object completamente separato che descrive come creare un nuovo utente. Entrambe le operation condividono l'identico URL slash users, ma la specifica le tratta come azioni logiche distinte, annidate sotto le rispettive chiavi dei metodi HTTP. All'interno di ogni Operation Object, in genere definirai due campi per stabilirne l'identità: il summary e l'operationId. Il summary è una breve string pensata per i lettori umani. Per il metodo get sul nostro path slash users, il summary potrebbe semplicemente essere: Elenca tutti gli utenti registrati. Appare nelle interfacce della documentazione generata, così i developer possono scansionare rapidamente gli endpoint disponibili. Ecco il punto chiave. Il campo operationId è pensato per le macchine. È una string univoca usata per identificare l'operation in tutto il tuo documento API. I code generator si basano pesantemente sull'operationId per dare un nome alle funzioni e ai metodi all'interno dei client SDK che costruiscono. Se dai alla tua operation get un operationId uguale a listUsers, il client Python o TypeScript generato avrà una funzione chiamata specificamente listUsers. Questa string deve essere assolutamente univoca. Se due operation condividono lo stesso operationId, i tool di generazione automatica produrranno codice rotto o crasheranno completamente. La struttura si basa su un nesting rigoroso e prevedibile. I path mappano sui Path Item, i Path Item mappano sui metodi HTTP, e i metodi mappano sugli Operation Object definiti da identificatori univoci. Padroneggiare questa esatta gerarchia garantisce che sia i developer umani che i tool di automazione a valle possano interagire con l'architettura della tua API senza dover tirare a indovinare. Per questo episodio è tutto. Alla prossima!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 6 di 19. Gli endpoint statici ti portano solo fino a un certo punto. Per creare un'API davvero utile, hai bisogno di un modo per passare argomenti dinamici direttamente nella request, per cambiare l'esecuzione di un'operazione o i dati a cui punta. Questo episodio è tutto dedicato agli endpoint dinamici con parametri. Iniziamo dal path dell'URL. In OpenAPI, definisci le sezioni dinamiche di un URL usando il path templating. Lo fai racchiudendo il nome di una variabile tra parentesi graffe. Pensa a un'API di e-commerce. Se vuoi recuperare un ordine specifico, il tuo path sarà tipo: slash orders slash parentesi graffa aperta orderId parentesi graffa chiusa. All'interno del tuo documento OpenAPI, descrivi questa variabile usando un Parameter Object. Specifichi la sua location impostando il campo in al valore path. A volte le persone cercano di rendere i path parameter opzionali. Non puoi farlo. Un path parameter definisce strutturalmente la route. Se il parametro manca, la route semplicemente non esiste. Per via di questa regola, qualsiasi parametro in cui la location è path deve sempre avere il campo required impostato a true. E se invece vuoi dei modificatori opzionali? Questo ci porta alla seconda location, dove il campo in è uguale a query. I query parameter compaiono esattamente alla fine dell'URL, dopo un punto interrogativo. Tornando alla nostra API di e-commerce, magari vuoi una lista di ordini, ma vuoi vedere solo quelli già in transito. Aggiungi punto interrogativo status equals shipped all'URL. A differenza dei path parameter, i query parameter non definiscono la location della risorsa. Filtrano o modificano il risultato, il che significa che il loro campo required può essere impostato a true o false. L'URL non è l'unico posto in cui puoi passare dei parametri. Il Parameter Object supporta altre due location. Impostare il campo in a header ti permette di definire degli header HTTP custom richiesti dalla tua operazione. Ad esempio, potresti richiedere un header custom che indichi uno specifico tipo di dispositivo client. Nota che gli header standard come Accept o Authorization sono rigorosamente esclusi dal Parameter Object, perché vengono gestiti altrove in OpenAPI. Infine, impostare la location a cookie ti permette di documentare i parametri passati tramite i cookie del browser, come ad esempio un session token temporaneo. Dichiarare dove si trova un parametro è solo il primo passo. Devi anche definire la sua struttura. All'interno del Parameter Object, usi il campo schema per definire il tipo di dato sottostante. Questo dice all'API consumer esattamente se quell'orderId è un integer, una string, o un formato specifico come un UUID. Poi hai il campo style. Questo stabilisce come il parametro viene serializzato nella request HTTP. La serializzazione è fondamentale quando passi dati complessi come array o oggetti. Se passi una lista di stati in una query string, il campo style ne determina il formato. Un valore di style pari a form potrebbe separare più valori con una e commerciale, mentre un valore di style pari a simple restituisce una lista separata da virgole. Combinando i campi location, schema e style, dai al client istruzioni precise su come formattare la network request. Ecco il punto chiave. Il Parameter Object non si limita a descrivere gli input per cortesia. Detta rigorosamente l'esatta impronta di ciò che un'operazione accetta, forzando i tipi di dato e i formati prima che venga eseguita una singola riga della logica del tuo backend. Se trovi utili questi episodi, puoi supportare lo show cercando DevStoriesEU su Patreon. Per questo episodio è tutto. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 7 di 19. Quando invii centinaia di campi a un'API, i query parameter diventano ingestibili. Hai bisogno di un pacchetto strutturato. Questo pacchetto è definito dalla strutturazione dei Request Body di input. Mentre le richieste GET si basano sull'URL path e sulla query string, le richieste POST, PUT e PATCH fanno il lavoro pesante trasportando un payload. Questo payload contiene dati complessi e annidati. Nelle vecchie specifiche Swagger 2.0, ti ricorderai di aver definito i body parameter o i form parameter direttamente accanto agli input di header e path. La versione 3 di OpenAPI ha cambiato radicalmente questo aspetto. Ha eliminato completamente i body parameter e ha introdotto un singolo Request Body Object dedicato. Il Request Body Object si trova a livello di operation nel design della tua API. La sua caratteristica distintiva è che si basa fortemente sulla content negotiation. Non ti limiti a descrivere i dati; mappi i dati a specifici media type. Questa mappatura avviene all'interno della content map. La content map è un dizionario in cui le chiavi sono MIME type standard, come application slash json, e i valori sono Media Type Object che descrivono in dettaglio l'aspetto di quello specifico payload. Prendi ad esempio un client che fa l'upload di un nuovo profilo utente. Il profilo contiene un nome, un indirizzo email, le preferenze dell'utente e un address object annidato. Invece di incastrare tutto questo nelle variabili dell'URL, il client invia un payload JSON. Nel tuo documento OpenAPI, sotto il request body, crei una content map con la chiave esatta application slash json. Questo dichiara esplicitamente che l'API accetta solo JSON per questa operation. Se un client prova a inviare XML o plain text, il server sa immediatamente di dover rifiutare la request con un errore di unsupported media type. Questa struttura è estremamente flessibile. Se l'upload del tuo profilo utente richiede un'immagine del profilo insieme ai dati testuali, lo gestisci esattamente nello stesso punto. Aggiungi una seconda chiave alla content map per multipart slash form-data. Questo Media Type Object specifica quindi le regole per il payload misto. Ogni media type ottiene la sua definizione indipendente. Questo permette allo stesso identico endpoint API di elaborare formati di dati fondamentalmente diversi, basandosi esclusivamente sull'header Content-Type che il client invia nella HTTP request. All'interno del Request Body Object stesso, accanto alla content map, troverai un flag required. Si tratta di una semplice proprietà booleana. Impostarlo a true significa che la request fallirà immediatamente se il client invia un body vuoto. Forza la presenza del payload prima ancora che il server tenti di validare i dati al suo interno. Le vere e proprie regole strutturali del payload stesso sono gestite da uno schema associato al Media Type Object, anche se le meccaniche avanzate del design del JSON Schema saranno trattate nell'episodio dieci. Ecco il punto chiave. Il Request Body Object disaccoppia il payload di dati grezzi dai transport parameter HTTP, consentendo a un singolo endpoint di forzare regole di validazione completamente diverse basate unicamente sul media type dichiarato nella content map. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 8 di 19. La maggior parte degli sviluppatori documenta l'happy path, ma la vera resilienza di un'API deriva dal definire rigorosamente ed esattamente come si verificheranno i fallimenti. Se dici ai client solo cosa succede quando tutto va alla perfezione, la tua API è documentata solo a metà. Oggi esamineremo le Expectations ed Error Responses. In OpenAPI, le response rappresentano la garanzia contrattuale definitiva. Formalizzano la promessa che, se il client invia una request specifica, l'API restituirà un payload noto o un errore strutturato. Questa promessa è gestita dal Responses Object. Pensalo come una routing table per i risultati. Le chiavi in questa map sono gli HTTP status code scritti come string, come ad esempio il testo "200" o "404". I valori associati a queste chiavi sono i singoli Response Object, che descrivono in dettaglio cosa viene restituito al client over the wire. Ecco un concetto chiave sulla formattazione di questi object. In gran parte di OpenAPI, i campi description sono completamente opzionali. Li usi quando vuoi aggiungere un contesto utile per altri sviluppatori. In un Response Object, il campo description è strettamente obbligatorio. Se lo ometti, l'intera definizione della tua API diventa non valida. Non deve per forza essere un lungo paragrafo. Una frase breve e precisa che spieghi il risultato è sufficiente, ma il parser ne imporrà la presenza. Considera uno scenario pratico in cui un client richiede uno specifico profilo utente. Per il risultato di successo, definisci una chiave per la string "200". All'interno di quel Response Object, fornisci la tua description obbligatoria, magari scrivendo "Recupero utente riuscito". Successivamente, definisci il campo content. Questo campo mappa un media type, più comunemente "application/json", direttamente allo schema che definisce la struttura del tuo user object. Il codice client ora sa esattamente quali property aspettarsi quando la chiamata ha successo. Questo copre il risultato previsto. Ora devi documentare il fallimento. Sotto lo stesso Responses Object, definisci un'altra chiave per "404". La description richiesta potrebbe essere semplicemente "Utente non trovato". Proprio come nel caso di successo, il campo content qui mappa "application/json" a uno schema, ma questa volta punta alla tua struttura di errore standardizzata. Grazie a questo contratto esplicito, la client application può parsare in modo sicuro la error response e mostrare un prompt utile all'utente finale, anziché crashare su dati imprevisti. Ci saranno sempre casi in cui non potrai prevedere ogni singolo error code che la tua architettura potrebbe produrre. Un reverse proxy potrebbe lanciare un 502 Bad Gateway, oppure un web application firewall potrebbe iniettare un 403 Forbidden. È qui che entra in gioco la wildcard default. Invece di un HTTP status code numerico, usi la parola esatta "default" come chiave. Questa funge da definizione catch-all. Se il server restituisce un qualsiasi status code che non hai elencato esplicitamente nel Responses Object, il client fa fallback sulla struttura definita sotto default. Funge da rete di sicurezza per l'error handling generico, garantendo che il client sappia comunque come leggere l'error payload. Una definizione API veramente robusta non si limita a spiegare lo scenario perfetto; fornisce una map precisa e prevedibile per ogni possibile modo in cui il sistema può fallire. Grazie per aver trascorso qualche minuto con me. Alla prossima, stammi bene.

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 9 di 19. Se la tua API ha 100 endpoint e tutti restituiscono la stessa identica struttura di paginazione, il copia e incolla è una ricetta per il disastro. Una piccola modifica al nome di un field significa dover cercare manualmente 100 definizioni sparse in tutto il documento. Il meccanismo strutturale che risolve questo problema è la Reusability con i Components. La specifica OpenAPI affronta il problema del bloat della specifica attraverso una sezione dedicata a livello root chiamata Components Object. Pensala come un dizionario centralizzato o una library interna per la definizione della tua API. Invece di definire data structure complesse, query parameter standard o response del server ripetitive inline sotto ogni singolo path, li dichiari esattamente una volta all'interno del Components Object. Questo stabilisce una rigorosa single source of truth. Prima di spiegare i meccanismi, devo chiarire un malinteso comune su come si comporta questa sezione. Definire uno schema, un header o un parameter all'interno del Components Object non lo espone automaticamente nella documentazione della tua API o nella tua logica di routing. La sezione components è completamente passiva. Non ha alcun effetto diretto sui tuoi endpoint. Un component è rilevante solo se un path o un'operation reale punta esplicitamente ad esso. Per chiamare in causa un component, usi il Reference Object. Nella sintassi OpenAPI, questo è rappresentato dalla keyword dollar-sign-ref. Il Reference Object utilizza un JSON Pointer per dire ai tool esattamente dove trovare la definizione condivisa. Una stringa di pointer interno standard inizia con un simbolo di cancelletto, seguito da uno slash, la parola components, un altro slash, il nome specifico della categoria e infine il nome custom che hai dato al tuo object. Facciamo un esempio concreto. Quasi ogni API richiede un modo coerente per restituire gli errori client e server. Vuoi che le tue response 400 Bad Request e 500 Internal Server Error condividano la stessa identica struttura su tutti gli endpoint, magari contenendo un error code intero e una stringa di messaggio descrittiva. Per prima cosa, scendi al tuo Components Object a livello root. Al suo interno, apri una categoria chiamata schemas. Sotto schemas, definisci un nuovo object generico chiamato ErrorModel e specifichi le tue property code e message. La tua struttura di errore generica è ora salvata in modo sicuro. Successivamente, passi ai path della tua API. Quando definisci la response di livello 400 per un endpoint di creazione utente, eviti completamente di scrivere le property dello schema inline. Invece, fornisci una chiave dollar-sign-ref. Il suo valore è il path esatto verso il tuo schema salvato: hash-slash-components-slash-schemas-slash-ErrorModel. Inserisci quella stessa identica stringa di reference nella response di livello 500. Ripeti questa reference in tutti i tuoi endpoint di fatturazione, i tuoi endpoint di autenticazione e i tuoi endpoint di ricerca. Decine di operation ora puntano a una singola definizione. Questa strategia organizzativa si estende ben oltre gli schemas. Il Components Object fornisce categorie specifiche per vari elementi dell'API. Puoi salvare argomenti di paginazione standard all'interno della categoria parameters. Puoi definire intere strutture di payload in requestBodies, o requisiti di autorizzazione standard in securitySchemes. La logica operativa rimane identica per tutti. Definisci l'object una volta sola nel suo bucket corrispondente, poi collegalo ai tuoi path operativi usando una reference. Ecco il punto chiave. Creare una specifica API manutenibile significa fondamentalmente controllare la duplicazione. Quando emerge un nuovo requisito che ti obbliga ad aggiungere un field timestamp a ogni response di errore, utilizzare i components significa che modifichi l'ErrorModel in un solo punto, e ogni operation nell'intera API eredita automaticamente l'aggiornamento. Per questo episodio è tutto. Alla prossima!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 10 di 19. Sai cos'è un integer, ma il tuo database deve sapere se si tratta di un valore a 32 o 64 bit. Gli schemi colmano questa lacuna. Questo episodio è interamente dedicato ai Data Type e agli schemi. Lo Schema Object funge da rigoroso motore di validazione per la tua API. Si trova direttamente sotto i tuoi parameter, request body e response. Invece di limitarsi a dire a un client di inviare un payload JSON generico, uno schema definisce la forma, il type e i limiti esatti di quei dati. Agisce come un filtro rigoroso al confine del tuo sistema. Se una request in arrivo non corrisponde alle regole definite nello schema, fallisce la validazione prima ancora che la logica della tua applicazione la veda. Storicamente, i developer si sono imbattuti in un grosso punto di attrito nella definizione di queste regole. La versione 3.0 di OpenAPI utilizzava un proprio dialetto personalizzato di JSON Schema. Era simile allo standard, ma fondamentalmente incompatibile in alcuni aspetti frustranti, causando infiniti grattacapi con il tooling. La versione 3.1 di OpenAPI risolve completamente questo problema. Non è più un dialetto personalizzato. OpenAPI 3.1 è ora completamente allineato con il moderno JSON Schema. Nello specifico, funge da superset del JSON Schema Draft 2020-12. Questo significa che qualsiasi documento JSON Schema standard che hai già a disposizione è automaticamente uno schema OpenAPI 3.1 valido. Essere un superset significa semplicemente che OpenAPI aggiunge alcune keyword specifiche per le API, come gli identificatori di configurazione XML, senza rompere lo standard sottostante. Al centro di queste regole di schema c'è la keyword type. OpenAPI si basa sui data type primitivi definiti da JSON Schema. Hai string, integer, number e boolean. La distinzione tra number e integer è rigorosamente applicata. Il type number gestisce i valori floating-point e double, mentre il type integer rifiuta specificamente qualsiasi valore con una frazione decimale. Ecco il punto chiave. Sapere che qualcosa è semplicemente una string o un integer raramente fornisce un contesto sufficiente per un sistema backend. È qui che il modificatore format diventa essenziale. La keyword format restringe un type primitivo generico a qualcosa di specifico per cui il tuo codice può allocare memoria o su cui può eseguire la validazione. Il type primitivo indica al parser JSON come leggere i dati grezzi, mentre il format indica alla tua applicazione esattamente come interpretare il valore. Ad esempio, se definisci una property come integer, puoi aggiungere un format int32 o int64 per specificarne l'esatta dimensione in byte. Se il tuo type è una string, puoi applicare un format come date-time, password o email. La specifica OpenAPI definisce un registro standard di questi format, ma il campo è in definitiva una string aperta, il che significa che il tooling può supportare format custom se la tua applicazione lo richiede. Analizziamo uno scenario concreto. Devi definire un object User per un endpoint di registrazione. Inizi creando uno schema di type object. All'interno di questo object, definisci due property, un ID e un indirizzo email. Per la property ID, imposti il type su integer e il format su int64. Per la property dell'indirizzo email, imposti il type su string e il format su email. Infine, specifichi un array di property required contenente i nomi sia del campo ID che del campo email. Ora hai un contratto rigoroso ed eseguibile. Se un client invia una property email che non assomiglia a un indirizzo email valido, o un ID che supera il limite numerico di 64 bit, l'API gateway o il framework rifiuta immediatamente il payload. La precisione al confine dell'API ti evita di scrivere infinite logiche di controllo dei dati all'interno dei tuoi controller. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 11 di 19. Prima di poter proteggere un endpoint sensibile, devi dichiarare formalmente e con precisione come è fatto un badge ID valido. Non puoi semplicemente richiedere l'autenticazione a un client. Devi specificare il meccanismo esatto che deve utilizzare, gli URL che deve chiamare e i parametri che deve inviare. Definire i security schemes è il modo in cui risolvi questo problema. Pensa a questo passaggio come a un inventario delle serrature presenti nel tuo sistema. Stai descrivendo i tipi di serrature disponibili, ma non le stai ancora installando su porte specifiche. In OpenAPI, definisci queste serrature all'interno dell'oggetto components, in particolare in una sezione chiamata security schemes. Ogni serratura ottiene un nome di riferimento personalizzato a tua scelta. All'interno di questo nome personalizzato, dichiari il suo type e le sue properties richieste. Ci sono cinque tipi principali di security schemes nella specifica OpenAPI tre punto uno. Il primo è il type http. Questo copre i meccanismi di autenticazione HTTP standard definiti dalla RFC 7235, come l'autenticazione Basic o Bearer. Per definire uno scheme per un token HTTP Bearer standard, crei una voce sotto security schemes. Imposti la property type sulla string http, e imposti la property scheme sulla string bearer. Puoi anche aggiungere facoltativamente una property bearer format per dare un indizio sul tipo di token, ad esempio fornendo la string JWT. Ecco il punto chiave. Quando usi lo scheme http bearer, la specifica presuppone implicitamente che il token verrà inviato nell'header HTTP Authorization standard. Non devi dire a OpenAPI dove guardare. Ma il secondo type, lo scheme api key, è completamente diverso. Per una API key, devi specificare esplicitamente sia la property name, che è il nome esatto del campo, sia la property in, che stabilisce dove va inserita la chiave. La property in accetta solo tre valori: query, header o cookie. Se ti aspetti un header personalizzato come X API Key, usa il type api key. Se stai usando gli header Authorization standard, usa il type http. Il terzo type è oauth2. Questo richiede una configurazione più strutturata perché OAuth2 ha diversi flows distinti. Per definire un flow authorization code di OAuth2 complesso, inizi impostando il type su oauth2. Poi fornisci un oggetto flows. All'interno di flows, aggiungi un oggetto authorization code. Questo oggetto annidato richiede due URL specifici. Fornisci l'authorization url dove l'utente effettua il login, e il token url dove l'applicazione scambia un codice con un token. Devi anche fornire un oggetto scopes, che mappa nomi di scope specifici a brevi descrizioni testuali di ciò che quegli scope consentono. Il quarto type è open id connect. Questo è molto più semplice da dichiarare rispetto a OAuth2. Imposti il type su open id connect e fornisci una singola property open id connect url. Questa punta direttamente al noto documento di discovery che i client usano per configurarsi automaticamente. Infine, il quinto type è mutual T L S, che sta per mutual Transport Layer Security. Imposti semplicemente il type su mutual T L S. Questo segnala che il client deve fornire un certificato X 509 durante l'handshake TLS iniziale per autenticarsi, completamente al di fuori del livello applicativo HTTP. La cosa più utile da ricordare qui è che definire i security schemes separa il meccanismo di autenticazione dagli endpoint che lo richiedono. Costruisci le tue serrature una sola volta in un catalogo centralizzato, assicurandoti che i client sappiano esattamente come formattare le loro credenziali prima ancora di provare a bussare. A proposito, se vuoi supportare lo show, puoi cercare DevStoriesEU su Patreon. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. OpenAPI e Swagger Ecosystem, episodio 12 di 19. Applicare la sicurezza è un gioco di equilibrio: vuoi bloccare l'intero vault a livello globale, ma lasciare la lobby aperta ai visitatori. Per farlo senza chiuderti fuori, devi capire come OpenAPI applica i Security Requirement. Una volta definiti i tuoi security scheme nella sezione components del tuo documento OpenAPI, devi effettivamente collegarli ai tuoi endpoint. Lo fai usando il security array. Questo array contiene dei Security Requirement Object, che fanno riferimento ai nomi degli scheme che hai creato prima. Puoi dichiarare questo security array in due punti: a livello globale nella root del tuo documento OpenAPI, o a livello locale dentro uno specifico Operation Object. Se lo definisci nella root, ogni singolo endpoint della tua API eredita quel requirement. Se lo definisci dentro un'operation, fa l'override completo della configurazione globale. Non fa il merge con i setting globali, li sostituisce del tutto. Immagina uno scenario in cui imposti un requirement globale per cui ogni route dell'API ha bisogno di un Bearer token. Questo mette al sicuro il vault. Ma hai anche una route di login. Se la route di login eredita quel requirement globale del token, i nuovi utenti non potranno mai autenticarsi perché non hanno ancora un token. Devi fare l'override del blocco globale. Un errore comune è semplicemente omettere il campo security sull'operation di login, dando per scontato che questo implichi l'assenza di sicurezza. Se tralasci il campo, l'operation usa semplicemente il requirement globale di default, e i tuoi utenti rimangono chiusi fuori. Per permettere esplicitamente l'accesso anonimo, devi definire il security array sull'operation di login e metterci dentro un oggetto vuoto. Quell'oggetto vuoto dice a OpenAPI che il requirement per accedere a questo specifico endpoint è assolutamente nulla. Il blocco globale viene bypassato, e i visitatori possono raggiungere la lobby. È qui che la cosa si fa interessante. Il modo in cui strutturi gli elementi nel security array detta la logica della tua autenticazione. Gestisce scenari di OR logico e AND logico basandosi puramente sui confini dell'oggetto. Se il tuo array contiene due Security Requirement Object separati, per esempio, un oggetto che chiede una API key e un secondo oggetto separato che chiede OAuth2, questo crea un OR logico. L'API accetterà una request se il client soddisfa il primo oggetto o il secondo oggetto. Se ti serve un AND logico, cambi i confini. Mettiamo che una request debba avere sia un token OAuth2 che una signature in un custom header. Metti entrambi i nomi di quegli scheme dentro un singolo Security Requirement Object. Dato che condividono lo stesso oggetto, l'API richiede che siano tutti validi prima di far passare la request. Quando scrivi questi oggetti, mappi il nome del tuo scheme a un array. Se stai usando OAuth2 o OpenID Connect, quell'array elenca gli scope specifici richiesti per l'operation, come leggere o scrivere dati. Se stai usando una API key o un basic HTTP scheme, gli scope non si applicano, quindi devi mappare il nome dello scheme a un array vuoto per soddisfare la specifica. La struttura fisica del tuo security array è il tuo strumento principale per definire la logica di accesso. Padroneggia la differenza di confini tra elencare gli elementi nell'array rispetto a elencarli all'interno di un singolo oggetto, e potrai costruire qualsiasi flusso di autenticazione di cui il tuo sistema abbia bisogno. Questo è tutto per questo episodio. Grazie per aver ascoltato, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 13 di 19. REST è fantastico per fare domande, ma cosa succede quando è la tua API a dover iniziare la conversazione? Le API asincrone con i webhook gestiscono questa situazione inviando i dati in push nel momento esatto in cui si verifica un evento, eliminando completamente la necessità di fare polling continuo. Storicamente, i consumer dovevano scrivere script che controllavano ripetutamente i tuoi endpoint per vedere se uno stato era cambiato. Questo era inefficiente sia per i loro server che per i tuoi. OpenAPI 3.1 ha risolto questo limite introducendo il campo webhooks direttamente nella root del documento OpenAPI. Questa aggiunta ha portato un supporto di primo livello per la comunicazione asincrona ed event-driven nelle specifiche API standard. Invece di documentare solo ciò che un client invia al tuo server, il campo webhooks ti permette di documentare l'esatto opposto. Definisci le richieste HTTP che la tua piattaforma avvierà e invierà al server del consumer. Devi tracciare una linea netta tra webhook e callback, dato che la specifica OpenAPI li gestisce in modo molto diverso. La differenza sta nel modo in cui viene registrato l'URL di destinazione. I callback vengono attivati da una specifica richiesta API attiva. Un client chiama un endpoint di subscription sulla tua API e fornisce un URL di destinazione direttamente lì, nel payload della richiesta. Dato che sono legati a un'operazione, i callback sono definiti all'interno di quello specifico operation object. I webhook vengono registrati out-of-band. Uno sviluppatore fa il login in una dashboard di gestione, va su una pagina di impostazioni e incolla il suo URL di destinazione in un form. Alla specifica API non interessa come è stato ottenuto l'URL. Dato che i webhook esistono indipendentemente da qualsiasi specifica chiamata API a runtime, vengono posizionati al livello più alto del tuo documento OpenAPI, esattamente accanto ai tuoi path e component standard. Per documentare un webhook, apri la map webhooks a livello root. Ogni key all'interno di questa map è una semplice string che dà il nome all'evento. Per esempio, potresti usare la string payment dot successful. Il valore associato a quella key è uno standard Path Item Object. Questa è esattamente la stessa struttura che usi per definire i tuoi normali endpoint REST. All'interno di quel Path Item Object, dichiari il metodo HTTP che la tua piattaforma userà per consegnare l'evento, che quasi sempre è una richiesta POST. Ecco il punto chiave. La prospettiva è completamente ribaltata, ma i tool rimangono identici. Usi degli schema object standard per definire il request body che la tua piattaforma invierà. Nello scenario payment dot successful, specifichi che il payload sarà un JSON object contenente un payment ID univoco, l'importo esatto addebitato e un timestamp. Puoi anche definire gli header, il che è fondamentale per i webhook perché di solito devi documentare un header con firma crittografica, in modo che il consumer possa verificare che il payload provenga effettivamente da te. Infine, documenti le response che ti aspetti di ricevere dal consumer. Potresti dichiarare che il tuo sistema si aspetta uno status code 200 OK entro tre secondi, altrimenti il tuo sistema riproverà la consegna più tardi. Standardizzando questa documentazione API inversa, dai ai consumer tutto ciò di cui hanno bisogno per generare il loro codice server. Sanno esattamente quale payload parsare, quali header validare e quali status code restituire. Il campo webhooks a livello root sposta l'API design da semplici interazioni request-response a un'architettura event-driven completamente documentata. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 14 di 19. Creare un utente è il primo passo, ma come fa un client automatizzato a sapere intuitivamente dove andare per recuperare quel profilo utente subito dopo? Potresti hardcodare il workflow nel codice del tuo client, ma questo smette di funzionare nel momento in cui la struttura della tua API cambia. La soluzione a questo problema sono le State Transitions con i Link. In OpenAPI, l'oggetto Link si trova all'interno di una response e mappa i dati di quella response ai parametri di un'altra operation. Per essere chiari, i link non eseguono automaticamente le request. Non trasformano OpenAPI in un motore di orchestrazione attivo. Forniscono semplicemente istruzioni statiche ai tuoi tool, agli SDK o alla documentazione su come costruire la request logica successiva in un workflow. Se hai già sviluppato API in passato, potresti pensare che suoni esattamente come il puro HATEOAS, in cui il server invia link hypermedia dinamici all'interno del payload della response. I link di OpenAPI offrono un'alternativa developer-friendly a questo approccio. Invece di costringere il backend a iniettare URI dinamici in ogni singola response a runtime, i link di OpenAPI descrivono le transizioni di stato del workflow in modo statico all'interno della definizione stessa dell'API. I tool client possono comprendere il workflow senza dover parsare i payload live per scoprire quali azioni sono possibili. La logica si sviluppa collegando una response di origine a una operation di destinazione. Prendi ad esempio una request POST standard usata per creare un nuovo utente. La response restituisce un body JSON contenente un ID utente appena generato. All'interno di quella specifica definizione di response, aggiungi una mappa links. Ogni entry in questa mappa definisce una relazione con un'altra operation, come la request GET che recupera il profilo utente. Identifichi la operation di destinazione usando uno di due campi mutuamente esclusivi. Il primo è l'operation ID, che è una semplice string che corrisponde all'identificatore univoco della operation di destinazione. Il secondo è l'operation reference, che usa un JSON Pointer standard per navigare nel documento OpenAPI e individuare il path di destinazione e il metodo HTTP. L'operation ID è generalmente più pulito se la tua API li definisce in modo coerente, mentre l'operation reference è utile per puntare a operation in documenti OpenAPI esterni. Una volta puntato alla operation di destinazione, devi fornirle i dati corretti. Lo fai usando una mappa parameters. Le chiavi in questa mappa rappresentano i nomi dei parametri che la operation di destinazione si aspetta, come ad esempio il path parameter dell'ID utente. I valori sono runtime expression che indicano ai tool da dove estrarre quei dati dal contesto corrente. Una runtime expression è una sintassi specifica che valuta i dati durante la chiamata API. Puoi scrivere un'espressione che istruisce il client a guardare nel response body, individuare il campo ID ed estrarne il valore. Non sei limitato al response body. Le runtime expression possono estrarre valori dai response header, dal request path originale o dai query parameter della request originale. Se la operation di destinazione richiede un request body invece di soli parametri, l'oggetto Link fornisce un campo request body. Questo ti permette di mappare una runtime expression direttamente nel payload della request successiva. Quando un generatore di SDK elabora questi link, può creare automaticamente chiamate a metodi in chain, permettendo a uno sviluppatore di creare un utente e chiamare immediatamente un metodo generato per recuperare il profilo sull'oggetto restituito. Ecco il punto chiave. Il vero potere dell'oggetto Link è che colma il divario tra endpoint isolati, trasformando un dizionario piatto di path API in una mappa navigabile di azioni che i tuoi client possono seguire con sicurezza senza affidarsi a URL hardcoded. Grazie per aver ascoltato, ci sentiamo alla prossima.

Ciao, sono Alex di DEV STORIES DOT EU. OpenAPI e Swagger Ecosystem, episodio 15 di 19. Una specifica JSON, per quanto ben scritta, è inutile se i developer che consumano la tua API si rifiutano di leggerla. Devi renderla visiva. Ed è proprio qui che entrano in gioco gli Interactive Docs con Swagger UI. Finora abbiamo trattato un documento OpenAPI come un semplice file di testo raw contenente endpoint e schemi. Swagger UI prende quel file JSON o YAML e lo trasforma in una pagina web interattiva. Questo sposta completamente l'attenzione dalla scrittura della specifica al suo consumo attivo. I developer possono navigare tra gli endpoint, ispezionare i query parameter ed eseguire richieste HTTP live direttamente dal loro browser. Funge da ponte tra un contratto statico e un live testing tool. Se vuoi hostare questa interfaccia autonomamente, probabilmente inizierai con Node Package Manager. Quando andrai a installarlo, ti imbatterai subito in una comune trappola di naming. Ci sono due pacchetti principali. Il primo si chiama semplicemente swagger trattino ui. Non usare questo pacchetto a meno che tu non stia eseguendo un build tool come Webpack o Rollup per compilare un'applicazione front-end custom. Se il tuo obiettivo è semplicemente hostare la documentazione direttamente, hai bisogno del pacchetto chiamato swagger trattino ui trattino dist. Il suffisso dist sta per distribution. Contiene gli asset statici pre-built e pronti all'uso, come i core JavaScript bundle, gli stylesheet CSS e un file index HTML. Ti basta copiare questi file su un qualsiasi web server di base e funzioneranno immediatamente. Se non vuoi gestire pacchetti node o file locali in alcun modo, puoi embeddare quegli stessi identici asset statici in una pagina web vuota usando una content delivery network come unpkg. Aggiungi un tag style HTML standard che punta al file CSS di Swagger UI su unpkg, e un tag script per il JavaScript bundle. Poi, scrivi un breve blocco di inizializzazione in JavaScript che punta all'indirizzo web in cui si trova il tuo file OpenAPI. Il browser carica la pagina vuota, recupera gli asset dalla rete, ottiene la tua specifica e renderizza automaticamente l'interfaccia completa. Ecco il punto chiave. Non devi nemmeno scrivere codice HTML per fare il deploy di questa interfaccia. Il metodo più pulito e scalabile è usare l'immagine Docker ufficiale. Ti basta fare il pull dell'immagine chiamata swaggerapi slash swagger trattino ui. Eseguendola completamente out of the box caricherà un esempio Petstore di default. Per servire invece un tuo file locale, monti la tua specifica nel container come volume. Poi, passi una variabile d'ambiente chiamata SWAGGER underscore JSON, puntandola al percorso esatto in cui hai montato quel file all'interno del container. Per prima cosa, esegui il comando Docker run e mappi una porta esposta come la ottanta sulla tua macchina locale. Successivamente, mappi la tua directory locale contenente il tuo file swagger punto json a una directory all'interno del container. Infine, imposti la variabile d'ambiente SWAGGER underscore JSON per puntare a quello specifico file path interno. Quando il container parte, avvia un web server leggero, legge la tua variabile d'ambiente per individuare la specifica e serve la UI. Ottieni un portale di documentazione completamente funzionante in pochi secondi senza installare una singola dependency locale. Disaccoppiando il rendering della documentazione dal source code dell'API stesso, Swagger UI trasforma un contratto di testo statico in un testing environment eseguibile che viaggia senza problemi su qualsiasi infrastruttura. Grazie per aver passato qualche minuto con me. Alla prossima, stammi bene.

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 16 di 19. La documentazione della tua API ci mette dieci secondi a caricarsi, e ogni volta che un ingegnere vuole mostrare un endpoint specifico a un collega, deve scrivere a mano le istruzioni su come scorrere la pagina per trovarlo. Le impostazioni di default sono fatte per essere modificate. Modifichiamo l'interfaccia in modo che i tuoi sviluppatori trovino esattamente quello di cui hanno bisogno in pochi millisecondi. Questo episodio è tutto dedicato alla personalizzazione della Swagger UI. Prima di modificare qualsiasi cosa, dobbiamo fare una distinzione netta. Le impostazioni di cui stiamo parlando non vanno inserite nel tuo documento di specifica OpenAPI. Queste sono configurazioni a runtime. Stai modificando l'interfaccia che renderizza il documento, non il documento stesso. Puoi iniettare questi parametri in due modi. Se ospiti tu stesso i file della UI, passi un oggetto di configurazione al costruttore Javascript di Swagger UI quando si carica la pagina web. Se usi l'immagine Docker ufficiale di Swagger UI, passi queste stesse identiche proprietà direttamente al container come variabili di ambiente. L'impostazione fondamentale dice all'interfaccia dove trovare la tua specifica. Se hai una sola API, usi il parametro chiamato url, al singolare, e gli passi un path come stringa. Ma se hai un'architettura a microservizi con diverse API distinte, usi il parametro urls, al plurale. Gli passi un array che contiene degli oggetti, ognuno con un nome e un link. Questo genera in automatico un menu a tendina nella barra superiore della UI, permettendo all'utente di passare da una definizione API all'altra in modo fluido. Ora, immagina un'enorme API enterprise con centinaia di path e data model complessi. Se Swagger UI prova a renderizzare tutto questo sullo schermo in una volta sola, il browser si blocca. Il parametro che controlla questo comportamento è docExpansion. Di default, è impostato sulla parola list, che espande tutti i tag di primo livello ma nasconde i dettagli delle operazioni. Puoi cambiarlo in full, che espande assolutamente tutto sulla pagina. Tuttavia, per risparmiare tempo di caricamento su un'API enorme, ti conviene impostare docExpansion su none. Questo forza la UI a caricarsi completamente collassata. Fa risparmiare un sacco di memoria e renderizza all'istante, lasciando che l'utente apra solo quello di cui ha davvero bisogno. Una volta che l'utente trova quello che gli serve, vorrà condividerlo. Di default, cliccare sulle operazioni nella Swagger UI non cambia la barra degli indirizzi del browser. Se imposti il parametro deepLinking su true, la UI aggiunge un frammento hash all'URL ogni volta che un utente espande un endpoint o un tag. I tuoi sviluppatori possono copiare quell'URL esatto e mandarlo a un collega, facendolo atterrare con precisione su un'operazione specifica invece che in cima alla pagina. Ecco il punto chiave. Se la tua documentazione esiste principalmente per fare da sandbox, devi ridurre gli attriti. Normalmente, un utente deve cliccare su un pulsante con scritto Try it out su un'operazione per sbloccare i campi di input. Se imposti il flag tryItOutEnabled su true, quei campi di input sono attivi nel momento in cui l'operazione viene espansa. L'utente può semplicemente scrivere ed eseguire senza quel click in più. Personalizzare la Swagger UI a runtime ti dà il potere di plasmare l'esperienza della documentazione intorno all'intento dell'utente, trasformando un rendering generico in uno strumento ad alte prestazioni su misura per il tuo team. Grazie per averci ascoltato. Alla prossima, ciao a tutti.

Ciao, sono Alex di DEV STORIES DOT EU. OpenAPI e Swagger Ecosystem, episodio 17 di 19. Scrivere le spec OpenAPI a mano in un normale text editor è un incubo di typo e parentesi disallineate. Hai bisogno di un ambiente che ti urli contro nel millisecondo in cui indenti male un path. Questo è esattamente ciò che ti offre progettare con Swagger Editor. Swagger Editor non è una semplice text box. È un Integrated Development Environment creato appositamente per lo standard OpenAPI. Il suo compito principale è aiutarti a fare design, definire e documentare la tua API da zero. Il layout è diviso. La parte sinistra contiene il tuo codice YAML o JSON raw. La parte destra mostra la documentazione interattiva renderizzata. Ecco il punto chiave. L'editor valida la tua sintassi rispetto alla spec OpenAPI in real time. Se scrivi male il nome di un object o dimentichi un campo required, ti segnala istantaneamente l'errore, dicendoti esattamente quale riga è rotta. Non devi lanciare un build script separato per scoprire che la tua indentazione è sbagliata. Dobbiamo chiarire una cosa riguardo alle versioni. Il classico Swagger Editor, conosciuto come versione 4, è un tool legacy. Supporta pienamente OpenAPI 2.0 e 3.0. Non è sviluppato nativamente per OpenAPI 3.1.0. Se incolli una spec 3.1.0 nell'editor classico, fallirà la validazione. Per le spec 3.1.0 moderne, devi passare a Swagger Editor Next, che tratteremo nel finale. Ma per il lavoro standard su 3.0, l'editor classico rimane profondamente integrato in molti workflow. Puoi usare l'editor classico direttamente nel tuo browser senza installare nulla. Tuttavia, incollare design di API proprietarie in un sito web pubblico è un modo veloce per far arrabbiare il tuo security team. È qui che entra in gioco l'esecuzione in locale. Puoi far girare Swagger Editor in locale sulla tua macchina. Puoi installarlo usando npm, pullando il package swagger-editor e avviando un server locale. Un approccio ancora più pulito è usare Docker. Pulli l'immagine swaggerapi slash swagger-editor e tiri su un container mappato sulla tua porta locale. Questo fa girare l'esatto stesso visual editor interamente sulla tua macchina. Questo setup permette ai team di fare design in sicurezza dietro un firewall aziendale, senza esporre spec non ancora rilasciate all'internet pubblico. Tutta la validazione in real time avviene in locale. Dato che l'editor fornisce un feedback visivo istantaneo, fai design più velocemente. Mappi i tuoi path, definisci i tuoi data model e verifichi immediatamente che la documentazione risultante abbia senso. Catturi gli errori strutturali durante la fase di design, molto prima di scrivere la tua logica di backend. Se stai trovando utili questi episodi, puoi supportare lo show cercando DevStoriesEU su Patreon. Il singolo aspetto più prezioso dell'editor è la sicurezza immediata che ti dà; una spec senza errori sullo schermo garantisce che i tuoi tool downstream funzioneranno senza problemi. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. Ecosistema OpenAPI e Swagger, episodio 18 di 19. Hai passato ore a disegnare la specification perfetta. Ora, guarda come scrive migliaia di righe di codice server per te in tre secondi. Questo è il vantaggio di automatizzare con Swagger Codegen. Innanzitutto, dobbiamo chiarire una trappola comune legata al versioning. Swagger Codegen versione due supporta esclusivamente le vecchie specification Swagger 2.0. Se utilizzi il moderno standard OpenAPI 3.0, devi usare Swagger Codegen versione tre. Questo episodio si concentra interamente sulla versione tre. Swagger Codegen è un engine basato su template che legge il tuo documento OpenAPI e costruisce automaticamente il codice dell'applicazione. Traduce i tuoi file di design in classi, interfacce e operazioni di network reali. Questa è la ricompensa finale dello sviluppo design-first. Invece di scrivere a mano centinaia di file di boilerplate per l'HTTP routing, il parsing dei parametri e gli object model, lasci che sia la macchina a gestire il lavoro ripetitivo. Il generatore produce due tipi principali di codice. Primo, costruisce degli SDK client. Se hai bisogno di un client Python, JavaScript o Go per parlare con la tua API, Codegen crea una libreria pronta all'uso. Il package client gestisce automaticamente le richieste HTTP, la formattazione degli URL e il parsing delle risposte. Gli sviluppatori frontend o altri team di microservizi possono semplicemente importare questa libreria generata e chiamare i metodi nativamente, invece di scriversi a mano le richieste di network. Secondo, genera dei server stub. Un server stub è lo scheletro strutturale della tua applicazione backend. Include l'API routing, i data model e i layer di validazione dell'input. Collega tutto quanto, così il server può avviarsi e mettersi in ascolto del traffico immediatamente. Il codice generato intercetta le richieste HTTP in entrata, valida il payload rispetto al tuo schema OpenAPI e passa i dati puliti a una funzione vuota. Il tuo unico lavoro come sviluppatore è riempire quelle funzioni vuote con la tua vera business logic, come query al database o calcoli. Vediamo passo passo come eseguirlo. Swagger Codegen viene solitamente eseguito da command-line interface usando un file Java archive. Apri il tuo terminale ed esegui il comando Java con il flag trattino jar, puntando al file swagger-codegen-cli punto jar. Gli passi il comando generate. Poi, fornisci tre flag essenziali. Usi trattino i per specificare il tuo file di input, come openapi punto yaml. Usi trattino l per impostare il linguaggio e il framework di destinazione. Ad esempio, passare spring dice al tool di costruire un'applicazione Java Spring Boot. Infine, usi trattino o per specificare la directory di output di destinazione. Esegui il comando. In pochi secondi, il tool fa il parsing della specification. Mappa ogni string, integer e array definiti nel tuo documento OpenAPI ai tipi nativi equivalenti in Java. Si appoggia a una libreria di template logici pre-costruiti per il framework di destinazione, per unire insieme questi tipi. Il risultato è una struttura di directory completa, piena di controller, file di configurazione e data class. Puoi compilare subito quella directory di output, avviare il server e chiamare con successo gli endpoint che hai disegnato. Ecco il punto chiave. La code generation non ti fa solo risparmiare tempo all'inizio. Guidando la struttura del tuo server e le tue librerie client direttamente dallo stesso file OpenAPI, garantisci che la tua implementazione combaci perfettamente con il tuo contratto, portando a zero gli errori di integrazione tra i team. Questo è tutto per questo episodio. Grazie per aver ascoltato, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. OpenAPI and Swagger Ecosystem, episodio 19 di 19. Le API REST non sono più l'unico modo in cui i sistemi comunicano. È arrivato il momento di un tool che capisca Kafka e le architetture event-driven tanto bene quanto HTTP. Questo tool è Swagger Editor Next. Conosciuto anche come versione 5, si tratta di una completa riscrittura dell'interfaccia standard che probabilmente già conosci. Il classico Swagger Editor è profondamente legato alle API HTTP sincrone e a tecniche di rendering datate. Funziona bene con OpenAPI 3.0, ma può bloccarsi o rallentare durante la validazione di file particolarmente grandi. Swagger Editor Next sostituisce quell'infrastruttura datata. È interamente basato su un moderno stack React e Webpack. Questa è la parte che conta. L'input di testo sottostante ora è gestito dal Monaco Editor. È esattamente la stessa tecnologia che fa girare Visual Studio Code. Dato che si basa su Monaco, Swagger Editor Next gestisce file di specifica enormi senza intoppi. Offre un syntax highlighting robusto, un rilevamento immediato degli errori e una validazione precisa a livello di riga che supera di gran lunga la versione classica. In pratica stai digitando dentro un IDE leggero, anziché in un web form. Questo per quanto riguarda il motore. Ma che dire delle specifiche vere e proprie? Swagger Editor Next porta con sé due importanti funzionalità native. Primo, supporta OpenAPI 3.1.0 out of the box. Questa specifica versione di OpenAPI è pienamente allineata con JSON Schema, il che significa che puoi costruire data model e componenti riutilizzabili molto più complessi rispetto a quanto potevi fare nella versione 3.0. Secondo, Swagger Editor Next renderizza nativamente le specifiche AsyncAPI. Questa è la strada definitiva per i dev che gestiscono microservizi event-driven insieme alle API tradizionali. AsyncAPI usa una struttura molto simile a OpenAPI, ma invece di definire path HTTP e richieste GET, documenta message broker, topic ed eventi asincroni. Per vedere come funziona nella pratica, pensa a una rete di una smart city che gestisce l'illuminazione stradale. Se avessi a disposizione solo tool per REST, potresti provare a forzare un endpoint HTTP POST per rappresentare uno stream costante di dati dei sensori. Con Swagger Editor Next, ti basta scrivere un documento AsyncAPI. Definisci un channel chiamato smart-city-streetlights. Assegni Kafka come protocollo. Poi, specifichi un'operazione di publish che descrive in dettaglio l'esatta struttura JSON che il sensore emette quando si accende una luce. Mentre digiti la tua specifica sul lato sinistro dello schermo, il Monaco Editor valida la sintassi AsyncAPI. Sul lato destro, l'interfaccia renderizza un documento visivo strutturato e interattivo. Mostra chiaramente i topic Kafka, i payload dei messaggi attesi e gli header del protocollo. Non hai più bisogno di toolchain separate per le tue API sincrone e i tuoi microservizi event-driven. L'ecosistema si è evoluto per gestirli entrambi simultaneamente. Il passaggio agli eventi asincroni non significa dover ricominciare da zero con la tua documentazione; richiede semplicemente un editor moderno in grado di leggere quei nuovi standard. Dato che questo conclude la nostra serie, prenditi un momento per leggere la documentazione ufficiale, apri Swagger Editor Next e prova a modellare tu stesso un topic Kafka. Se hai un'idea per una serie completamente nuova, visita devstories dot eu e faccelo sapere. Per questo episodio è tutto. Ci sentiamo alla prossima!