Immagine descrittiva del post

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 creare una 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.1.

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.1</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.1</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

Come accennato poco fa, occorre creare una configurazione per documentare le API con Swagger2. Creiamo allora un file SwaggerConfig.java che estende WebMvcConfigurationSupport in questo modo:

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2).select()
				.apis(RequestHandlerSelectors.basePackage("guru.springframework")).paths(PathSelectors.any()).build()
				.apiInfo(this.apiInfo()).useDefaultResponseMessages(false);
	}
	@Override
	protected void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}
	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();
	}
}

Utilizziamo le annotazioni a livello di classe @Configuration e @EnableSwagger2, rispettivamente per marcarla come classe di configurazione Spring e abilitare l’utilizzo di Swagger2.

 

Documentare le API

Adesso che abbiamo configurato springfox all’interno dell’applicazione dobbiamo documentare le nostre API.

Per semplicità, utilizzerò un progetto Spring Boot creato nell’articolo già citato all’inizio di questo post, lo trovi qui. Utilizzeremo le API definite nel progetto, aggiungendoci le annotazioni swagger.

Prendiamo il metodo getById della classe ApplicationUserController:

/**
  * 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 = "the unique user id") @PathVariable("id") Long id) {
    ApplicationUserDto result = this.applicationUserService.getById(id);
    return result != null ? ResponseEntity.ok(result) : ResponseEntity.notFound().build();
}

Le annotazioni @ApiOperation e @ApiParam servono per descrivere i metodi dei controllers e servono per la generazione automatica della documentazione. In particolare, il primo descrive l’operazione, il secondo i parametri (path, query, body, …) della richiesta.

 

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.

swagger ui api page

 

http://localhost:8080/swagger-ui.html

Cosa fare ora?

Le configurazioni viste poco fa sono sufficienti per generare in automatico la pagina swagger-ui.html. Nessun altro sforzo è richiesto per documentare le API. Tutto qui.

Non resta che testare le nostre API utilizzando swagger.

 

Link di riferimento:

No comment yet, add your voice below!


Add a Comment

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *