Backend API e Web Services REST API Java

OpenAPI e Swagger: documentare e testare le REST API con Swagger UI, Editor e Spring Boot

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.

Course description

Un contratto chiaro per ogni REST API

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.

Cosa imparerai

  • La differenza tra OpenAPI, lo standard, e Swagger, l'ecosistema di strumenti, e perché serve un contratto tra backend e frontend
  • Leggere una Swagger UI: info, endpoint raggruppati per tag, schemas, parametri e codici di risposta
  • Provare le chiamate con Try it out e confrontarle con Postman e curl, con parametri e request body
  • La struttura del file openapi.json e come scriverlo in YAML con Swagger Editor
  • Creare un progetto Spring Boot con Spring Initializr ed Eclipse e generare specifica e Swagger UI con springdoc-openapi
  • Scrivere endpoint GET, POST e DELETE con ResponseEntity e i codici 200, 201, 204 e 404
  • Personalizzare la documentazione con @Bean OpenAPI, @Operation, @ApiResponses e @Schema
  • Separare input e output con i DTO e validare sul server con @Valid, @NotBlank, @Size e @Positive
  • Gestire gli errori con @RestControllerAdvice ed ExceptionHandler e documentare la risposta di errore in Swagger UI

Prerequisiti

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 chi è rivolto

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.

Lessons list

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...

Guarda lezione

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...

Guarda lezione

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 bod...

Guarda lezione
4/12 OpenAPI e Swagger (4): il file openapi.json e Swagger Editor in YAML
Premium

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 Edi...

Contenuto riservato Accedi
5/12 OpenAPI e Swagger in Java (5): progetto Spring Boot con Spring Initializr ed Eclipse
Premium

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 pr...

Contenuto riservato Accedi
6/12 OpenAPI e Swagger in Java (6): Springdoc in Spring Boot, primo endpoint e Swagger UI
Premium

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 (Concurr...

Contenuto riservato Accedi
7/12 OpenAPI e Swagger in Java (7): GET, POST e DELETE con ResponseEntity e AtomicLong
Premium

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ù th...

Contenuto riservato Accedi
8/12 OpenAPI e Swagger in Java (8): configurare OpenAPI con @Bean, @Operation e @ApiResponses
Premium

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...

Contenuto riservato Accedi
9/12 OpenAPI e Swagger in Java (9): DTO di richiesta e @Schema per documentare l'input
Premium

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...

Contenuto riservato Accedi
10/12 OpenAPI e Swagger in Java (10): validazione con @Valid, @NotBlank e DTO di risposta
Premium

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,...

Contenuto riservato Accedi
11/12 OpenAPI e Swagger in Java (11): errori con @RestControllerAdvice ed ExceptionHandler
Premium

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...

Contenuto riservato Accedi
12/12 OpenAPI e Swagger in Java (12): documentare la risposta di errore in Swagger UI
Premium

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...

Contenuto riservato Accedi
Giovanni Pace

Giovanni Pace

Ingegnere Informatico · Pratola Peligna

  • 107 Courses
About the teacher

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.

This course includes

  • Lessons 12
  • Duration 2h 49m
  • Difficulty intermedio
  • Language it
  • Certificate No

Recently viewed