Spring Boot: documentare le API con Swagger 2

In questo articolo voglio mostrarti un modo per documentare le API utilizzando Spring Boot e Swagger 2. Imparerai ad utilizzare le specifiche OpenApi all’interno del tuo progetto Spring Boot in modo automatizzato e veloce.

L’unica “difficoltà” consiste nel realizzare le tue API RESTful, argomento già visto nell’articolo Creare Servizi web RESTful con Spring Boot. Fatto questo, bastano davvero poche configurazioni per generare in modo automatizzato e rapido una documentazione efficace con tanto di interfaccia web.

Iniziamo?

Springfox e Swagger2

Swagger è un framework popolare per la generazione e l’utilizzo di specifiche OpenApi, nonché un modo utile per documentare le API RESTful di un’applicazione.

Springfox implementa la specifica Swagger 2 (o OpenAPI) rendendo la documentazione di API JSON automatizzata per API create con Spring.

Documentare le API con Swagger 2 in Spring Boot

Per utilizzare la suite springfox in Spring Boot dovrai innanzitutto aggiungere le dipendenze (Maven o Gradle) al progetto, successivamente definire e abilitare una nuova configurazione.

Continua a leggere.

Aggiungere le dipendenze

Aggiungi le dipendenze springfox Swagger2 e SwaggerUI, recuperabili dal mvnrepository centrale, al tuo progetto Spring Boot.

La versione più recente al momento della scrittura di questo articolo è la 2.9.2.

Utilizzando Maven:

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

Utilizzando Gradle:

implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

Aggiungere una configurazione

Una volta aggiunte le dipendenze, sarà sufficiente aggiungere l’annotazione @EnableSwagger2 per utilizzare una configurazione di default, ad esempio nella classe main:

@SpringBootApplication
@EnableSwagger2
public class Application {

	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}
}

Puoi anche decidere di inserire l’annotazione @EnableSwagger2 in una qualsiasi classe di configurazione (ovvero @Configuration) come vedrai tra pochi istanti.

Definire una nuova configurazione Swagger2

Anche se quanto hai appena visto è sufficiente a documentare le tue API, puoi decidere di definire una configurazione personalizzata.

Crea una nuova classe di configurazione SwaggerConfig, aggiungi l’annotazione @EnableSwagger2 (oltre a @Configuration) vista poco fa e utilizza l’oggetto Docket fornito dalla libreria per definire un nuovo bean, ad esempio:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
	                .select()
			.apis(RequestHandlerSelectors.any())
			.paths(PathSelectors.any())
			.build()
			.apiInfo(this.apiInfo())
			.useDefaultResponseMessages(false);
	}
	
	private ApiInfo apiInfo() {
		ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
		apiInfoBuilder.title("REST API");
		apiInfoBuilder.description("REST API Generation");
		apiInfoBuilder.version("1.0.0");
		apiInfoBuilder.license("GNU GENERAL PUBLIC LICENSE, Version 3");
		apiInfoBuilder.licenseUrl("https://www.gnu.org/licenses/gpl-3.0.en.html");
		return apiInfoBuilder.build();
	}
}

Puoi personalizzare diverse informazioni, ad esempio indicare il package che contiene le API da documentare tramite .apis(RequestHandlerSelectors.basePackage(“it.lateralecloud.controllers”)) oppure escluderne alcune con .paths(Predicates.not(PathSelectors.regex(“/error.*”))).

La lista completa dei parametri e tutto quello di cui hai bisogno per personalizzare la tua configurazione Swagger2, li trovi alla pagina Springfox Docs.

Cosa manca?

Con questi piccoli passaggi, sarai già in grado di generare in automatico la documentazione JSON delle tue API, in particolare il file /v2/api-docs.

Quello che puoi fare ora, è documentare singolarmente le operazioni assegnando un nome, una descrizione e altre opzioni di visualizzazione ai metodi, come vedrai continuando la lettura.

Documentare le API

Quello che stai per leggere ti permetterà di aggiungere ulteriore controllo alla documentazione. Non è però indispensabile, infatti, di default vengono documentati tutti i metodi appartenenti ai componenti Controllers Spring Boot.

Un esempio è il seguente:

@GetMapping("/{id}")
@ApiOperation(value = "Get user", notes = "Get user by id")
public UserDto getById(@ApiParam(name = "id", value = "Unique user ID", required = true) @PathVariable("id") Long id) 
{
    return userService.getById(id);
}

Anche in questo caso, potrai fare riferimento all pagina di documentazione Springfox Docs.

Ora, avvia la tua applicazione Spring Boot e collegati alla pagina /swagger-ui.html per osservare il risultato ottenuto.

L’interfaccia SwaggerUI permette, non solo di visualizzare la lista dettagliata di tutte le API, ma anche interagire con queste.

Utilizzare Swagger 2 con Spring Security

Se utilizzi Spring Security (qui un esempio) dovrai adottare delle accortezze per continuare ad usare Swagger2 e SwaggerUI. Si tratta di escludere dalla catena dei filtri i file Swagger, in questo modo:

@Override
public void configure(WebSecurity web) {
    web.ignoring().antMatchers("/v2/api-docs", "/configuration/**", "/swagger-resources/**",  "/swagger-ui.html", "/webjars/**", "/api-docs/**");
}

Queste risorse vengono generate dalla libreria Swagger2 e permettono, ad esempio, all’interfaccia SwaggerUI di essere caricata correttamente. In tutti gli altri casi, Spring Security restituirà un errore di autenticazione.

Link di riferimento:

GitHub del progetto demo: demo-api-service
Link esterni:
- Dipendenze springfox: swagger2 – swagger-ui
- Docs Springfox: Swagger docs

Laterale Cloud