In questo articolo vedrai un modo per documentare le API REST Spring Boot con lo standard OpenApi 3.
Cos’è OpenApi?
OpenApi è la specifica che definisce il formato per descrivere le API REST.
Documentare le API REST Spring Boot con OpenApi 3
Per documentare le API REST in Spring Boot utilizzando la specifica OpenApi 3 in modo automatizzato, basta usufruire della libreria springdoc-openapi, similmente a quanto visto in un articolo precedente con Springfox.
Per utilizzare la libreria springdoc-openapi è sufficiente aggiungere la dipendenza al progetto:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.7</version>
</dependency>Nota. Al momento della scrittura di questo articolo, la 1.6.7 è l’ultima versione disponibile.
La semplice aggiunta della dipendenza springdoc-openapi, permette ai progetti Spring Boot che si basano su spring-web, di fornire una documentazione delle API REST automatizzata senza necessità di ulteriori configurazioni. In altri casi, come ad esempio l’utilizzo di spring-webflux o spring-security, può essere utile integrare una dipendenza aggiuntiva per ottenere il supporto necessario, come dato dalla documentazione.
Personalizzare springdoc-openapi
Come hai appena visto, è sufficiente aggiungere la dipendenza springdoc-openapi al progetto per usufruire delle funzionalità della libreria utilizzando le configurazioni di default.
È possibile però personalizzare la documentazione delle API REST creando una nuova configurazione per OpenApi e definendo un nuovo Bean Spring OpenAPI, ad esempio:
@Bean
public OpenAPI openApi() {
return new OpenAPI()
.info(new Info()
.title("Title")
.description("Description")
.version("1.0.0")
.contact(new Contact()
.name("Alessandro Paperini")
.url("https://lateralecloud.it")
.email("alessandro@lateralecloud.it")));
}A questa pagina puoi trovare il javadoc per la classe OpenAPI.
Utilizzare le proprietà springdoc
Springdoc si basa sulle proprietà di configurazione Spring standard. Questo vuol dire che puoi inserire le proprietà di configurazione per springdoc all’interno del file application.properties (o yml) o in tutti gli altri file utilizzati per la configurazione di Spring.
Un esempio è il seguente:
springdoc.api-docs.enabled=false
Nella documentazione ufficiale trovi la lista di tutte le proprietà springdoc-openapi.
Interfaccia swagger-ui
La dipendenza springdoc-openapi-ui aggiunta include di per se swagger-ui supportandone le proprietà ufficiali.
Una volta avviata l’applicazione utilizzando la configurazione di default, è possibile accedere all’interfaccia Swagger alla pagina http://server:port/context-path/swagger-ui.html e la descrizione OpenAPI sarà disponibile al seguente URL per il formato JSON: http://server:port/context-path/v3/api-docs.
Come per le proprietà principali springdoc, è possibile inserire le proprietà swagger-ui all’interno del file di configurazione Spring utilizzando il prefisso springdoc.swagger-ui.
Ad esempio:
springdoc.swagger-ui.enabled=false
Qui la lista di tutte le proprietà utilizzabili.
Migrazione da SpringFox
Se il tuo progetto ha già un’implementazione SpringFox (come visto in questo articolo) e vuoi passare a Springdoc usufruendo dello standard OpenApi 3.0, puoi effettuare facilmente una migrazione come descritto nella documentazione ufficiale che trovi a questa pagina.
No comment yet, add your voice below!