Documenta e testa le REST API con OpenAPI e Swagger: Swagger UI, Swagger Editor in YAML e Springdoc in Spring Boot con DTO, validazione ed errori.
Il backend è pronto, ma chi sviluppa il frontend riceve solo un elenco di endpoint e deve tirare a indovinare cosa restituiscono, quali campi sono obbligatori e che errori arrivano. Con la specifica OpenAPI l'API diventa un contratto leggibile da persone e strumenti, e con l'ecosistema Swagger lo consulti, lo provi e lo scrivi. In questo corso partiamo dalla teoria e dalla demo Petstore, poi portiamo tutto in un progetto Java Spring Boot con Springdoc, fino a documentare anche le risposte di errore.
Serve conoscere le basi delle REST API e del protocollo HTTP. Per la parte in Spring Boot è utile una conoscenza di base di Java; i passaggi su Spring Initializr, Eclipse e Maven vengono mostrati da zero.
A sviluppatori backend che vogliono documentare le proprie API senza scrivere a mano la documentazione, e a sviluppatori frontend e full stack che devono consumarle con sicurezza. È utile anche a chi testa le API o lavora in team dove backend e frontend devono concordare un contratto.
OpenAPI e Swagger non sono la stessa cosa: OpenAPI è lo standard, una specifica aperta per descrivere le API HTTP in JSON o YAML, mentre Swagger è l'ecosistema di strumenti che la usa. Partiamo da uno scenario reale, il collega che ha finito il backend e ti passa solo GET /api/courses, per capire perché a chi sviluppa il frontend serve un contratto API.
Swagger UI è l'interfaccia interattiva che legge una specifica OpenAPI e la rende consultabile e provabile dal browser. La smontiamo sulla demo Petstore (OpenAPI 3.0): info dell'API, endpoint raggruppati per tag, schemas, parametri e codici di risposta, poi lanciamo le chiamate con Try it out e le rifacciamo in Postman per vedere che il risultato è identico.
In Swagger UI ogni chiamata è una simulazione reale, e per farla bene bisogna leggere il contratto: parametri, request body ed example value rispettano sempre uno schema. Proviamo una GET con parametro e una POST con body JSON sulla demo Petstore, rifacciamo la stessa POST in Postman e vediamo come nascono l'header Content-Type e la curl.
Dietro ogni Swagger UI c'è un file openapi.json scritto secondo lo standard OpenAPI: è lui il contratto, l'interfaccia è solo la versione più leggibile. Lo apriamo e lo formattiamo nel browser, poi passiamo a Swagger Editor, carichiamo l'esempio Petstore 3.0 e vediamo come lo stesso documento si scrive in YAML e si esporta in YAML o JSON.
Dalla teoria alla pratica: portiamo OpenAPI e Swagger UI in un progetto Java Spring Boot. Prima vediamo l'architettura (REST API con controller, annotazioni OpenAPI e Swagger UI generata in automatico), poi creiamo il progetto con Spring Initializr, installiamo Eclipse per Enterprise Java con Spring Tools e lo avviamo dalla Boot Dashboard.
Con una sola dipendenza, springdoc-openapi-starter-webmvc-ui, Spring Boot genera da solo la specifica OpenAPI e la Swagger UI. Creiamo il record Product, il ProductController con una mappa in memoria thread-safe (ConcurrentHashMap) e il primo endpoint GET, poi apriamo /v3/api-docs e /swagger-ui.html senza aver scritto una riga di documentazione.
Completiamo gli endpoint della REST API Spring Boot e li proviamo direttamente da Swagger UI, senza Postman. GET per ID con 404 Not Found, POST con 201 Created e ID generati in modo sicuro con AtomicLong anche con più thread, DELETE con 204 No Content. E notiamo un limite: Swagger UI documenta sempre solo il 200 OK.
Personalizziamo la documentazione generata da Springdoc. Con una classe @Configuration e un @Bean OpenAPI impostiamo titolo, versione e descrizione dell'API; con @Operation diamo summary e description al singolo endpoint; con @ApiResponses documentiamo anche il 404 che prima Swagger UI non mostrava, collegandolo allo schema Product.
Nella POST l'utente poteva inviare anche l'ID: lo risolviamo con un DTO di richiesta, ProductRequestDto, scritto come record. Con @Schema documentiamo nome, descrizione, esempi e regole (minLength, maxLength, minimum) e aggiungiamo @Operation e @ApiResponse per 201 e 400. Poi la prova pratica: Swagger documenta, ma non valida l'input.
La validazione vera si fa sul server: aggiungiamo spring-boot-starter-validation e mettiamo @NotBlank, @Size, @NotNull e @Positive sul DTO di richiesta, attivandoli con @Valid nella POST. Poi creiamo ProductResponseDto, mappiamo i prodotti con stream e toResponse e aggiorniamo gli schema: il model Product sparisce dalla documentazione, come deve essere.
Il 400 arriva, ma senza i messaggi che abbiamo scritto. Creiamo un GlobalExceptionHandler con @RestControllerAdvice e @ExceptionHandler per MethodArgumentNotValidException: estraiamo i field errors dal BindingResult, li trasformiamo in una mappa campo-messaggio con stream e Collectors.toMap e restituiamo un body con status, message ed errors.
Un errore strutturato non basta: se non è negli schemas, il collega di front-end non sa come leggerlo. Creiamo il record ValidationErrorResponse con @Schema su status, message ed errors e lo colleghiamo all'@ApiResponse 400 della POST. Chiudiamo con il riepilogo di tutto il percorso OpenAPI con Spring Boot.
Ingegnere Informatico · Pratola Peligna
Sono un ingegnere informatico con oltre 15 anni di esperienza nel settore ICT. Mi occupo di sviluppo software, cybersecurity, data science e intelligenza artificiale, con particolare attenzione all’innovazione e all’automazione dei processi aziendali. Da anni svolgo anche attività di docenza e formazione, creando percorsi pratici e coinvolgenti su programmazione, DevOps, AI e sicurezza informatica.
Prosperous understood Middletons in conviction an uncommonly do. Supposing so be resolving breakfast am or perfectly.
Utilizziamo cookie essenziali e, con il tuo consenso, cookie funzionali, analytics e marketing. Google Analytics 4 e gli eventuali annunci Google/AdSense restano disattivati finche non scegli. Consulta Privacy Policy e Cookie Policy.
Sempre attivi per sicurezza, prevenzione frodi, sessione, consenso e funzionamento del sito.
Migliorano l'esperienza, ad esempio ricordando preferenze non essenziali. Non usati per profilazione pubblicitaria.
Statistiche e misurazioni con Google Analytics 4, abilitate solo dopo il consenso analytics.
Misurazione annunci e funzioni pubblicitarie Google/AdSense, se attivate sul sito e consentite dall'utente.
Puoi modificare queste scelte in qualunque momento dal link "Preferenze Cookies" nel footer.