Spring Boot: documentare le API con Swagger2

In questo articolo voglio farti vedere un modo per documentare le API REST in Spring Boot e utilizzarle da interfaccia web. Se non hai ancora creato la tua prima API, dai un’occhiata a post come creare API RESTful utilizzando Spring Boot.

Springfox e Swagger2

Swagger è un framework popolare per la generazione e l’utilizzo di specifiche OpenApi, un modo per descrivere API REST.

Esiste un progetto, Springfox, che implementa quando appena detto, e fornisce un modo per la generazione automatica di JSON API da progetti Spring.

Utilizzare Springfox in un progetto Spring Boot

Per utilizzare la suite springfox all’interno di un progetto Spring Boot, è necessario aggiungere le sue dipendenze e abilitarne la configurazione.

Vediamo di cosa si tratta.

Aggiungere le dipendenze

Per realizzare quanto sto per dire occorrono due dipendenze recuperabili da mvnrepository centrale, una per swagger2 e l’altra per la UI.

Al momento della scrittura di questo post l’ultima versione è la 2.9.2.

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

Utilizzeremo queste le librerie springfox per generare in modo automatico l’interfaccia swagger con la quale visualizzare e utilizzare le API, partendo da annotazioni Spring inserite appositamente nelle classi Java.

Aggiungere una configurazione

Per abilitare Swagger2 sulla nostra applicazione Spring Boot è sufficiente aggiungere l’annotazione @EnableSwagger2 della libreria aggiunta, ad esempio, sulla classe dove è presente il metodo main (subito sotto @SpringBootApplication).

@SpringBootApplication
@EnableSwagger2
public class Application {

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

Cosi facendo, all’avvio dell’applicazione, verrà generato un file contenente tutta la documentazione Swagger (in formato Json). Per osservarne il risultato, basta collegarsi alla pagina /v2/api-docs.

All’aspetto sembrerà poco amichevole, ma per fortuna, sarà generata anche la pagina /swagger-ui.html, come vedrai più avanti.

Aggiungere una configurazione personalizzata

Prima di parlare dell’interfaccia UI di Swagger, è giusto chiedersi se, oltre alla configurazione di default, ci sia un modo per personalizzarla. Per farlo, possiamo utilizzare il componente Docket fornito dalla libreria springfox, che fornisce impostazioni predefinite e metodi convenienti per la configurazione.

Per migliorare la leggibilità delle classi del progetto, creiamo un nuovo file SwaggerConfig.java da utilizzare come configurazione per Swagger.

Spostiamo in questa classe Java l’annotazione vista in precedenza per abilitare Swagger2 e creiamo un nuovo Bean di tipo Docket come nell’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 a tuo piacimento tutte le informazioni, specificare il package che contiene le API da documentare, tipo .apis(RequestHandlerSelectors.basePackage("it.lateralecloud.controller")).

Puoi decidere di non documentare alcune API, escludendole dall’interfaccia Swagger, come quelle relative a Basic Error Controller generate da Spring .paths(Predicates.not(PathSelectors.regex("/error.*"))), oppure aggiungere un’autenticazione per accedere all’interfaccia.

Tutto quello di cui hai bisogno per configurare correttamente Swagger potrai trovarlo all’interno della pagina Springfox Docs.

Documentare le API

Adesso che abbiamo configurato springfox all’interno dell’applicazione possiamo documentare le API a nostro piacimento.

Questo passaggio non è indispensabile per la generazione della documentazione, infatti, di default vengono documentati tutti i metodi annotati come controller rest.

L’esempio sottostante si riferisce ad una API definita in un’altro articolo in cui viene trattato l’argomento su come creare API RESTful con Spring Boot.

Prendiamo il metodo getById della classe ApplicationUserController e documentiamolo in questo modo:

/**
  * Gets by id.
  *
  * @param id the id
  * @return the by id
*/
@GetMapping("/{id}")
@ApiOperation(value = "get user", notes = "get user by id")
public ResponseEntity getById(
    @ApiParam(name = "id", value = "Unique user id", required = true) @PathVariable("id") Long id) {
    ApplicationUserDto result = this.applicationUserService.getById(id);
    return result != null ? ResponseEntity.ok(result) : ResponseEntity.notFound().build();
}

Anche in questo caso, potrai approfondire ciò che hai appena visto spulciando nella pagina Springfox Docs.

Utilizzare l'interfaccia Swagger

Possiamo ora avviare l’applicazione e osservare il risultato visibile alla pagina swagger-ui.html. Sotto, lo screenshot della documentazione generata.

Utilizzare Swagger con Spring Security

Quando si accede alla pagina di documentazione Swagger UI, vengono caricati, attraverso chiamate HTTP, i file necessari alla creazione dell’interfaccia, come ad esempio il JSON api-docs.

Se stai utilizzando Spring Security, dovrai adottare delle accortezze per fare uso della pagina Swagger UI evitando errori di autenticazione. Se infatti hai configurato Spring Security come nell’esempio che trovi qui, allora, dovrai escludere dalla catena dei filtri di sicurezza le pagine che servono all’interfaccia Swagger: /v2/api-docs, /configuration/**, /swagger-resources/**, /swagger-ui.html, /webjars/**, /api-docs/**

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

Link di riferimento:

GitHub del progetto demo: demo-api-service
Articoli correlati: Creare Servizi Web RESTful con Spring Boot – Sicurezza delle API in Spring Boot
Link esterni:
- Dipendenze springfox: swagger2 – swagger-ui
- Docs Springfox: Swagger docs

Laterale Cloud